I am using Sphinx to document a code base docString; in python. I have code like this -
class foo(np.ndarray):
def foo_func():
pass
class bar(foo):
def bar_func():
pass
When using sphinx.ext.autosummary to document the code base, in bar, how do I prevent inherited members from foo from showing?
Related
using ruby 2.2, rails 4.1
I have a search result class that I would like to use to format the correct results depending on the type of search, ie full text, keyword, etc. Currently I have separate modules for the different search types in the result class, each one knows how to format it's own results. What I would like to do is pass the raw results and the type in to the search result initialize method and within the method, extend the correct module dynamically. then the class that instantiated the search result class (resultbuilder in this case) calls a method defined in the module to format the results. This would need to be called as an instance method, with the same method defined in each module so the resultbuilder just calls one method regardless of search type.
something like this:
Class SR
def initialize(data, type)
#data = data
extend type.constantize
end
module FullText
def call
<format results>
end
end
end
I can get the extend to work, tho I think I'm missing something as the call method is not available on the SR class instance.
Is there some other way to set up the modules? Do they have to be put into their own files? I prefer not to set up modules that I can dynamically use with generic call and results methods thereby keeping the details out of the resultbuilder.
I'm reading my ruby book. Looking at the code below,
module Destroy
def destroy(anyObject)
#anyObject = anyObject
puts "I will destroy the object: #{anyObject}"
end
end
class User
include Destroy
attr_accessor :name, :email
def initialize(name,email)
#name = name
#email = email
end
end
my_info = User.new("Bob","Bob#example.com")
puts "So your name is: #{my_info.name} and you have email #{my_info.email}"
user = User.new("john","john#example.com")
user.destroy("blah")
I could've just created another method inside my class. Why would I want to do this? Why would I want to use a module? It's not like embedding this into other classes is any easier than just using normal inheritance.
You can think of a module and the methods and constants inside of it as more of providing utility functions and actions that you can include to other objects as you see fit. For example, if you wanted to use destroy function in the objects Foo and Bar you would do similarly:
class Foo
include Destroy
# other code below
end
class Bar
include Destroy
# other code below
end
Now any Foo or Bar object has access to all the methods or constants inside of destroy.
Modules define a namespace, a sandbox in which your methods and constants can play without having to worry about being stepped on by other methods and constants. The ruby docs goes into more depth about this and includes a good example practical of when you would want to use it as seen below:
module Debug
def whoAmI?
"#{self.type.name} (\##{self.id}): #{self.to_s}"
end
end
class Phonograph
include Debug
# ...
end
class EightTrack
include Debug
# ...
end
ph = Phonograph.new("West End Blues")
et = EightTrack.new("Surrealistic Pillow")
ph.whoAmI? » "Phonograph (#537766170): West End Blues"
et.whoAmI? » "EightTrack (#537765860): Surrealistic Pillow"
In this example, every class that includes Debug has access to the method whoAmI? and other methods and constants that Debug includes without having to redefine it for every class.
Some programming languages such as C++, Perl, and Python allow one class to inherit from multiple other classes; that is called multiple inheritance. Ruby does not support multiple inheritance. That means each class can only inherit from one other class. However, there are cases where a class would benefit by acquiring methods defined within multiple other classes. That is made possible by using a construct called module.
A module is somewhat similar to a class, except it does not support inheritance, nor instantiating. It is mostly used as a container for storing multiple methods. One way to use a module is to employ an include or extend statement within a class. That way, the class gains access to all methods and objects defined within the module. It is said that the module is mixed in the class. So, a mixin is just a module included in a class. A single module can be mixed in multiple classes, and a single class can mix in multiple modules; thus, any limitations imposed by Ruby's single inheritance model are eliminated by the mixin feature.
Modules can also be used for namespacing. That is explained in this post at the Practicing Ruby website.
You are writing a module in the same file as the class, but not necessarily inside the class, but anyway.
For me there are 3 reasons to use a module(more details here):
Modules provide a namespace and prevent name clashes.
Modules implement the mixin facility.
When you have a very complex and dense class, you can split it into
modules and include them into the main class.
Your example is fairly simple, it would indeed make more sense to write the method in the class itself, but try to imagine a complex scenario.
Is there an autodoc-directive that will list all subclasses of a given class?
If I have the following Python-Code:
class Base(object):
pass
class A(Base):
pass
class B(Base):
pass
Is there a way to generate an Output like:
Classes implementing Base: A, B
Using Sphinx, Autodoc and Re-Structured text. (Like :show-inheritance: but backwards). Something like:
.. autoclass:: Base
:THE-COMMAND-I-AM-MISSING:
I have a class and a module which have the same names:
module Pushover
def configure
..
end
end
module MyModule
class Pushover
def blah
Pushover.configure
end
end
end
This doesn't work because the Pushover.configure call directs to the containing class. Now, an obvious fix would be to rename the class. However, the Module is from a gem and the class conforms to a naming convention required in a DSL. So ideally they should both stay the same. I could also create a second helper class and call via that, but that all seems a little hacky. My preferred solution would be to directly reference the module method.
All the existing questions around this area seem to be disambiguating in the opposite direction - i.e. they want to get the class reference not the module.
Is there any way for me to inform Ruby that I mean the module rather than the class when I specify Pushover?
If you don't want to look up the constant relative to the current scope, just use an absolute path:
::Pushover.configure
What are for you the pros and cons of using:
FooLib::Plugins
FooLib::Plugins::Bar
vs.
FooLib::Plugin
FooLib::Plugin::Bar
naming conventions? And what would you use or what are you using? What is more commonly used in the comunity?
Use:
module FooLib end
module FooLib::Plugins end
class FooLib::Plugins::Plugin; end #the base for plugins
class FooLib::Plugins::Bar < FooLib::Plugins::Plugin; end
class FooLib::Plugins::Bar2 < FooLib::Plugins::Plugin; end
or in a different words:
module FooLib
module Plugins
class Plugin; end #the base for plugins
class Bar < Plugin; end
class Bar2 < Plugin; end
end
end
Also arrange the files like this:
- foo_lib/
- plugins/
- plugin.rb
- bar.rb
- bar2.rb
This is how Rails does it (so this is the Rails Way). I.e. look at the Associations namespace and the Associations::Association class from which all of the classes form the Associations namespace inherits (i.e. Associations::SingularAssociation).
To me FooLib::Plugins appears like a module, used as a namespace which various plugin classes are kept in. FooLib::Plugin looks like a superclass for FooLib plugins.
In FooLib::Plugins::Bar, Bar definitely seems like the name of a plugin. With FooLib::Plugin::Bar, I would be doubtful whether Bar was a helper class used by Foo::Plugin, or the name of a plugin.
Assuming Plugin is a base class:
class FooLib::Plugin::Bar < FooLib::Plugin
This is the one I use and recommend. Bar is a Plugin in FooLib and it inherits from FooLib::Plugin. It also keeps the plugins provided by the FooLib library nested under the namespace of the general class, which reads naturally:
# Assign the Bar Plugin of the FooLib library to p.
p = FooLib::Plugin::Bar
If I were to develop a third party plugin for your library, I would create the following structure:
# Baz is a Plugin for the FooLib library provided by BarLib.
class BarLib::FooLib::Plugin::Baz < ::FooLib::Plugin
Note that I mirror the FooLib hierarchy, but under BarLib's namespace. I would not extend it directly.
class FooLib::Plugins::Bar < FooLib::Plugin
I have also used this one, and I think it makes the most sense. Bar extends FooLib::Plugin and is one of the Plugins provided by FooLib. However, it creates a potentially needless module.
I think this would be a great choice if Plugins was a central plugin repository that implements methods like Plugins.add, Plugins.all and Plugins.loaded.
Use it if you can justify the extra module.
class FooLib::Plugins::Bar < FooLib::Plugins
Doesn't make a lot of sense to me. Bar is one of the Plugins in FooLib, that part looks fine. However, it inherits from Plugins. Is it inheriting from more than one plugin? It sounds strange to me; the class name shouldn't suggest something that is impossible.
I would second the approach outlined by #jtrim.
Given that the module (i.e. Plugin) is being used for namespacing only, I typically override the new method in the module:
module Foo
module Plugin
def self.included(base)
raise "cannot be included"
end
def self.extended(base)
raise "cannot extend"
end
def self.new(*args)
Base.new(*args)
end
class Base;end
end
end
base_plugin_obj = Foo::Plugin.new(...)
Generally, the approach I tend to take is:
module Foo
module Plugin
class Base; end
end
end
class Foo::Plugin::Bar < Foo::Plugin::Base; end
The Base class for plugins is a convention found all over the place in the RubyOnRails codebase as well as many others. (e.g. ActiveRecord::Base, ActionController::Base, etc.)
I disagree with #Matheus Moreira's approach where Foo::Plugin is used both as the base class and the namespace for plugins.
The only functional reason why this shouldn't be done has to do with convention - in the Ruby community one will find many less instances of classes as namespaces than modules. The only time I really see classes used as a namespace for another class is when the purpose of said class is private to the namespace class and is not used externally.