If I have a file foo.baz.py:
from foo.bar.baz import Quux, Quuux
__all__ = ['Quux', 'Quuux']
I'd like to document the api as follows:
Baz
===
.. currentmodule:: foo.baz
.. autosummary::
:toctree: generated/
:nosignatures:
Quux
Quuux
This gives me an autosummary table with Quux and Quuux, and links to pages containing their full documentation. However, it requires me to explicitly list Quux and Quuux, so whenever I add a class, I have to manually add it to the documentation.
Instead, I'd rather like to do something like this, and have it automatically generate a table based on __all__, to get exactly the same output as above:
Baz
===
.. currentmodule:: foo
.. autosummary::
:toctree: generated/
:nosignatures:
baz
But this doesn't work, it produces a table with a single entry, the module baz, leading to a page with all its contents as well as a summary table.
Is there a way to achieve this? In case it's relevant, I'm using numpydoc.
Related
This file will be foo.pm6:
sub bar { "quux" }
say "Loaded";
And this one requirer.p6:
require "foo.pm6";
say bar;
require fails silently, not loading foo.pm6, and bar is not found. This also fails:
require foo;
say bar;
with the same error, about not finding bar. This file:
require ::"foo";
say bar;
Fails even strangely, with MVMArray: Can't shift from an empty array
UPDATE: it fails silently because it stops when it finds an unknown symbol, bar, so it's not running "It's loaded" before it produces the error. Still, the last error is weird.
Undeclared routine:
bar used at line 9. Did you mean 'bag', 'VAR'?
So once that is out of the way, is bar actually imported? If it is, in which package name? How can I use it?
You can use the lib to add the current directory to the library search path.
If I add the export trait to bar() in foo.pm6:
sub bar is export { "quux" }
say "Loaded";
the following seems to work (requirer.p6):
use v6;
use lib '.';
require foo <&bar>;
say bar;
Output:
Loaded
quux
I would like to require a file in Ruby without defining that file's constants on Object. Instead I would like to include them only in a module in the requiring file. For instance if I have a file foo.rb that looks like this:
module Foo
def self.hello_world
puts 'Hello, World.'
end
end
A representation of the result I hope to achieve looks something like this:
module Bar
require_relative './foo.rb'
end
Foo.hello_world
# NameError: uninitialized constant Foo
Bar::Foo.hello_world
# Hello, World.
It seems like the way things are required in Ruby, anything defined at the top level of another file will be defined as a constant on Object and thus globally available. I'm having a problem because I need something from a file that conflicts with a constant in the global namespace.
I recognize that this problem may be fundamental to Ruby, but is it possible there's some metaprogramming technique to overcome this issue?
It looks like the following snippet works for what I'm trying to do:
module Bar
class_eval File.open('./foo.rb').read
end
It may be that I'm still missing something though.
If you don't need to access the ancestor, what you're looking for is extend
module Foo
def hello_world
puts 'Hello, World.'
end
end
module Bar
extend Foo
end
Bar.hello_world
I need a line of code that can does something like this:
instance_eval(IO.read(File.expand_path('../../policyfiles/base.rb', __FILE__)))
But for multiple files... this does not work:
instance_eval(IO.read(File.expand_path('../../policyfiles/base.rb', '../../policyfiles/app.rb', __FILE__)))
Any idea on how to do this?
If you have a list and want to do things to each element, use each.
policy_files = ['../../policyfiles/base.rb', '../../policyfiles/app.rb']
policy_files.each { |file|
instance_eval(IO.read(File.expand_path(file, __FILE__)))
}
However a bare instance_eval should be avoided. It will load the contents of those files as if they were in the current scope. Any global variables will blow over your own and each other. For example...
$ cat policy.rb
foo = 42
def bar
99
end
$ cat test.rb
foo = 23
instance_eval(IO.read("policy.rb"))
puts foo
puts bar
$ ruby ~/tmp/test.rb
42
99
Because instance_eval runs the content of test2.rb inside test.rb's scope, that includes foo = 42. Surprise!
Instead use require_relative. This does the work of loading a relative file, but it won't mix up globals. You'll only get the methods.
policy_files.each { |file|
require_relative(file)
}
Now when we do the same thing, but with require_relative, your globals are safe.
$ cat policy.rb
foo = 42
def bar
99
end
$ cat test.rb
foo = 23
require_relative("policy.rb")
puts foo
puts bar
$ ruby ~/tmp/test.rb
23
99
Now globals in the policy file can't muck up the caller.
require_relative has the additional advantage that it will only load a given file once. That means any code can safely load these files without considering whether something else has already loaded them.
Note that it seems odd that the user of the policies has to load the base policy. I can't say for sure without knowing what these files do, but I suspect app.rb should handle loading base.rb.
Also note that using relative paths might not be the best thing to do. If you reorganize your code files, they'll all break. Instead, consider adding the top level library directory to $LOAD_PATH.
lib_dir = ...whatever you need to figure this out...
$LOAD_PATH.unshift(lib_dir)
Then, assuming policyfiles/ is at the top of the library tree, you can require("policyfiles/app.rb") from any file in the project no matter its location.
I want to be able to statically analyze my code. That is, to know from the plain text of the file where every function and variable comes from. IDEs and text editor plugins work better when they can trace the origin of every symbol as well.
So for example, if I have application code like this:
#...
Y.some_method()
#...
Then I want to see Y in an include/import/require/extend/def statement somewhere on the page.
In other languages I use, one can explicitly choose which sub-parts of a namespace to bring in to the current context.
Python:
from X import Y
Haskell:
import X (Y)
Elixir:
alias X.Y, as: Y
And while it's possible to import all contained names in Python, the "wildcard import" is frowned upon:
from X import *
". . . they make it unclear which names are present in the namespace, confusing both readers and many automated tools."
In Ruby, it seems that this fully implicit "wildcard" way is the only way to bring in a contained name:
include X
This makes Y available, but is there some way to make this explicit? The docs for Ruby include don't show any options.
What I'd really like to do in Ruby is something like one of these:
from X include Y
include X::Y as Y
The best I've come up with so far is:
require 'x/y' ; Y = X::Y
Here's a crazy hack in the answer to another question which would enable this.
Try this. But I agree with #tadman that you should consider doing it in the Ruby way.
Object.define_singleton_method(:include) do |*mths, from: nil|
mod = from || mths.first
mod = mod.dup
if from
all_mths = mod.instance_methods
(all_mths - mths).each { |mth| mod.send :undef_method, mth }
end
super(mod)
end
module Foobar
def foo
puts :foo
end
def bar
puts :bar
end
end
class Abc
include Foobar
end
Abc.new.foo # => 'foo'
Abc.new.bar # => 'foo'
class AbcWithoutBar
include :foo, from: Foobar
end
AbcWithoutBar.new.foo # => 'foo'
AbcWithoutBar.new.bar # => NoMethodError
Ruby always executes the code that you require
And since there is no partial execution of a file there cannot be partial require.
When you require a feature Ruby locates the corresponding file using the load paths in $: and then double checks against the list of loaded files in $" and if the file has not yet been loaded executes the file.
Ruby is a dynamic language, the best way to reason about its source code is halting a running program rather than statically. In fact even class and def are not declarations but just method calls that are executed at runtime. Consider for example this contrived example
class Surprise < [Array, Hash, Fixnum, Object].sample
end
If you want to know where a method or class has been defined best use pry. You can require pry and then use binding.pry to stop anywhere in your source code and spelunk around to inspect objects and source code. Two of the most useful commands are ls and $
ls prints all methods of an object or class
$ prints the file location and source code of a method
My "file 1"
C:\Ruby200\lib\ruby\gems\2.0.0\gems\page-object-0.9.2\lib\page-object.rb
and my directory
C:\Ruby200\lib\ruby\gems\2.0.0\gems\page-object-0.9.2\lib\page-object
are located on my hard drive as a consequence of page-object gem installation.
In the contents of "file 1", among the other lines of code, I see the following line:
require 'page-object/page_populator'
Lower in the same file, I see:
module PageObject
include PagePopulator
Looking at "file 2"
C:\Ruby200\lib\ruby\gems\2.0.0\gems\page-object-0.9.2\lib\page-object\page_populator.rb
these lines are at the top of this file:
module PageObject
module PagePopulator
Based on the Ruby tutorials that I read, that say that after requiring "file 2" into "file 1" using require, modules from "file 2" need to be included into the "file 1" with include.
I would expect "file 1" to have
include PageObject::PagePopulator
instead of
include PagePopulator
However, since it is not setup this way, and page-object is a widely-used gem, I believe that having the PageObject module in both files eliminates the need for
include PageObject::PagePopulator
because
include PagePopulator
is sufficient.
I wanted to confirm that my assumption is right.
Having read about Module.nesting method and also having read the links returned by googling "reopening classes/modules" query, I still didn't find the answer to my question.
I will try to describe it again.
content of file_a is below:
require "file_b"
module Foo
include Bar
...
end
content of file_b is below:
module Foo
module Bar
...
end
Where is the explanation that we shouldn't use
in file_a the following:
include Foo::Bar
instead of
include Bar
and the way I have written it before:
include Bar
is sufficient
What would be the difference if we have
file_c with the following content:
module Bar
...
end
Does it mean that there is no difference in including module from this file_c versus file_b?
content of file_a with module from file_b and module from file_c is below:
require "file_b"
require "file_c"
module Foo
include Bar
...
end
If this is the case what is the point of having module Foo in file_b?
I think what you are trying to ask about is the rules for constant lookup in ruby: when you write Bar in your code, how does ruby find the value of that constant?
What files things are in is irrelevant, what matters is that within
module Foo
...
end
A reference to Bar will try Foo::Bar and then the top level ::Bar constant ( constant scoping is lexically scoped)
So in the case where Foo::Bar has been previously defined then
module Foo
include Foo::Bar
end
And
module Foo
include Bar
end
Do the same thing.
The Module.nesting method will show you this lookup chain. Ruby will also search the ancestors of the currently open class / module. There are some gotchas / corner cases, but those are the basics.