As the documentation says, an enumeration is a set of symbolic names (members) bound to unique, constant values. The PEP8 says that constants are usually named as UPPER_CASE, should I use this notation in Python 3.4 enums? If yes, why the examples in the docs are using lower_case?
Update
The BDFL (Benevolent Dictator For Life) has spoken, and the Enum documentation has changed to reflect all upper-case member names.
The examples in the [previous] docs are lower-case primarily because one of the preexisting modules that Enum was based on used lower-case (or at least its author did ;).
My usage of enum has usually been something along the lines of:
class SomeEnum(Enum):
... = 1
... = 2
... = 3
globals().update(SomeEnum.__members__)
which effectively puts all the members in the module namespace.
So I would say whichever style feels more comfortable to you -- but pick a style and be consistent.
I think they're not UPPER_CASE because, well, it just looks weird when it is. Since you can only access the enumerations through the class (e.g. my_enum.VALUE) it looks weird if the members are capitalized. In C the members of the enumeration go into the module namespace, so it doesn't look weird (to me) when the members are capitalized, in usage:
typedef enum {OFF, ON} lightswitch;
lightswitch bathroomLight = ON;
But in Python you access them through the enumeration class that you create, and it looks weird to go from ClassStyle names to ALL_CAPS.
class Lightswitch(Enum):
OFF = 0
ON = 1
# isn't that weird?
my_light = Lightswitch.OFF
Bottom line, I think it's just aesthetic. I've been wrong before, though, and I realize that this is just my opinion.
When in doubt about style, I usually defer to the style used in standard library code and examples from the official documentation. It keeps me from wasting time on arbitrary decisions.
So in this case, I recommend lower case, like variable names.
Related
I am new to programming in general. I would like to know why this symbol is being used in a few codes. What I mean is, what is the purpose of this way of declaring a variable? Is it useful?
For example let's say I define
say_hello1 = "hello everybody"
I could also define the same variable using:
say_hello2 : str = "hello everybody"
Or ..
say_hello3 : float = "hello everybody" # I know this is not a float variable, I'm doing it on purpose
Each variable (say_hello1, say_hello2 and say_hello3 ) will be the same type (string). So what is the purpose of this way of declaring variables? Is it just to say that the variable will be a specific type? Or does it change anything else (i.e the efficency of the code)?
Thanks in advance.
It shows what variable you are expecting, which makes your code a lot easier to read and understand. It can also help with linters and other third party tools. Python itself won’t look at it afaik.
Take a look here: https://docs.python.org/3/library/typing.html
Python is not a strongly-typed language. The variable : type is just for readability, does not declare strongly typed variables. Later you can change the value, even in another type.
Type hints were introduced in PEP-484. The goal is to allow additional tools to do static linting based on the acceptable types for a variables. This is included for example in PyCharm, and is used by mypy.
But anyway, Python is a dynamic language, and the interpretor just ignores those declared type hints.
In this case the type is pretty obvious so it is not very helpful but assume that you have a base class BaseClass that some other classes inherit SubClassA and SubClassB, then:
a: SubClassA = SubClassA() # not very useful
a: BaseClass = SubClassA() # indicates that you expect a given interface, no necessarily SubClassA
### another dev can safely replace code later on
a: BaseClassA = SubClassB()
I'd like to provide documentation (within my program) on certain dynamically created objects, but still fall back to using their class documentation. Setting __doc__ seems a suitable way to do so. However, I can't find many details in the Python help in this regard, are there any technical problems with providing documentation on an instance? For example:
class MyClass:
"""
A description of the class goes here.
"""
a = MyClass()
a.__doc__ = "A description of the object"
print( MyClass.__doc__ )
print( a.__doc__ )
__doc__ is documented as a writable attribute for functions, but not for instances of user defined classes. pydoc.help(a), for example, will only consider the __doc__ defined on the type in Python versions < 3.9.
Other protocols (including future use-cases) may reasonably bypass the special attributes defined in the instance dict, too. See Special method lookup section of the datamodel documentation, specifically:
For custom classes, implicit invocations of special methods are only guaranteed to work correctly if defined on an object’s type, not in the object’s instance dictionary.
So, depending on the consumer of the attribute, what you intend to do may not be reliable. Avoid.
A safe and simple alternative is just to use a different attribute name of your own choosing for your own use-case, preferably not using the __dunder__ syntax convention which usually indicates a special name reserved for some specific use by the implementation and/or the stdlib.
There are some pretty obvious technical problems; the question is whether or not they matter for your use case.
Here are some major uses for docstrings that your idiom will not help with:
help(a): Type help(a) in an interactive terminal, and you get the docstring for MyClass, not the docstring for a.
Auto-generated documentation: Unless you write your own documentation generator, it's not going to understand that you've done anything special with your a value. Many doc generators do have some way to specify help for module and class constants, but I'm not aware of any that will recognize your idiom.
IDE help: Many IDEs will not only auto-complete an expression, but show the relevant docstring in a tooltip. They all do this statically, and without some special-case code designed around your idiom (which they're unlikely to have, given that it's an unusual idiom), they're almost certain to fetch the docstring for the class, not the object.
Here are some where it might help:
Source readability: As a human reading your source, I can tell the intent from the a.__doc__ = … right near the construction of a. Then again, I could tell the same intent just as easily from a Sphinx comment on the constant.
Debugging: pdb doesn't really do much with docstrings, but some GUI debuggers wrapped around it do, and most of them are probably going to show a.__doc__.
Custom dynamic use of docstrings: Obviously any code that you write that does something with a.__doc__ is going to get the instance docstring if you want it to, and therefore can do whatever it wants with it. However, keep in mind that if you want to define your own "protocol", you should use your own name, not one reserved for the implementation.
Notice that most of the same is true for using a descriptor for the docstring:
>>> class C:
... #property
... def __doc__(self):
... return('C doc')
>>> c = C()
If you type c.__doc__, you'll get 'C doc', but help(c) will treat it as an object with no docstring.
It's worth noting that making help work is one of the reasons some dynamic proxy libraries generate new classes on the fly—that is, a proxy to underlying type Spam has some new type like _SpamProxy, instead of the same GenericProxy type used for proxies to Hams and Eggseses. The former allows help(myspam) to show dynamically-generated information about Spam. But I don't know how important a reason it is; often you already need dynamic classes to, e.g., make special method lookup work, at which point adding dynamic docstrings comes for free.
I think it's preferred to keep it under the class via your doc string as it will also aid any developer that works on the code. However if you are doing something dynamic that requires this setup then I don't see any reason why not. Just understand that it adds a level of indirection that makes things less clear to others.
Remember to K.I.S.S. where applicable :)
I just stumbled over this and noticed that at least with python 3.9.5 the behavior seems to have changed.
E.g. using the above example, when I call:
help(a)
I get:
Help on MyClass in module __main__:
<__main__.MyClass object>
A description of the object
Also for reference, have a look at the pydoc implementation which shows:
def _getowndoc(obj):
"""Get the documentation string for an object if it is not
inherited from its class."""
try:
doc = object.__getattribute__(obj, '__doc__')
if doc is None:
return None
if obj is not type:
typedoc = type(obj).__doc__
if isinstance(typedoc, str) and typedoc == doc:
return None
return doc
except AttributeError:
return None
I have a module, errors.py in which several global constants are defined (note: I understand that Python doesn't have constants, but I've defined them by convention using UPPERCASE).
"""Indicates some unknown error."""
API_ERROR = 1
"""Indicates that the request was bad in some way."""
BAD_REQUEST = 2
"""Indicates that the request is missing required parameters."""
MISSING_PARAMS = 3
Using reStructuredText how can I document these constants? As you can see I've listed a docstring above them, but I haven't found any documentation that indicates to do that, I've just done it as a guess.
Unfortunately, variables (and constants) do not have docstrings. After all, the variable is just a name for an integer, and you wouldn't want to attach a docstring to the number 1 the way you would to a function or class object.
If you look at almost any module in the stdlib, like pickle, you will see that the only documentation they use is comments. And yes, that means that help(pickle) only shows this:
DATA
APPEND = b'a'
APPENDS = b'e'
…
… completely ignoring the comments. If you want your docs to show up in the built-in help, you have to add them to the module's docstring, which is not exactly ideal.
But Sphinx can do more than the built-in help can. You can configure it to extract the comments on the constants, or use autodata to do it semi-automatically. For example:
#: Indicates some unknown error.
API_ERROR = 1
Multiple #: lines before any assignment statement, or a single #: comment to the right of the statement, work effectively the same as docstrings on objects picked up by autodoc. Which includes handling inline rST, and auto-generating an rST header for the variable name; there's nothing extra you have to do to make that work.
As a side note, you may want to consider using an enum instead of separate constants like this. If you're not using Python 3.4 (which you probably aren't yet…), there's a backport.enum package for 3.2+, or flufl.enum (which is not identical, but it is similar, as it was the main inspiration for the stdlib module) for 2.6+.
Enum instances (not flufl.enum, but the stdlib/backport version) can even have docstrings:
class MyErrors(enum.Enum):
"""Indicates some unknown error."""
API_ERROR = 1
"""Indicates that the request was bad in some way."""
BAD_REQUEST = 2
"""Indicates that the request is missing required parameters."""
MISSING_PARAMS = 3
Although they unfortunately don't show up in help(MyErrors.MISSING_PARAMS), they are docstrings that Sphinx autodoc can pick up.
If you put a string after the variable, then sphinx will pick it up as the variable's documentation. I know it works because I do it all over the place. Like this:
FOO = 1
"""
Constant signifying foo.
Blah blah blah...
""" # pylint: disable=W0105
The pylint directive tells pylint to avoid flagging the documentation as being a statement with no effect.
This is an older question, but I noted that a relevant answer was missing.
Or you can just include a description of the constants in the docstring of the module via .. py:data::. That way the documentation is also made available via the interactive help. Sphinx will render this nicely.
"""
Docstring for my module.
.. data:: API_ERROR
Indicates some unknown error.
.. data:: BAD_REQUEST
Indicates that the request was bad in some way.
.. data:: MISSING_PARAMS
Indicates that the request is missing required parameters.
"""
You can use hash + colon to document attributes (class or module level).
#: Use this content as input for moo to do bar
MY_CONSTANT = "foo"
This will be picked up by some document generators.
An example here, could not find a better one: Sphinx document module properties
the following worked for me with Sphinx 2.4.4:
in foo.py :
API_ERROR = 1
"""int: Indicates some unknown error."""
then to document it:
.. automodule:: foo.py
:members:
I think you're out of luck here.
Python don't support directly docstrings on variables: there is no attribute that can be attached to variables and retrieved interactively like the __doc__ attribute on modules, classes and functions.
Source.
The Sphinx Napoleon Python documentation extension allows to document module-level variables in an Attributes section.
Per https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html :
Attributes
----------
module_level_variable1 : int
Module level variables may be documented in either the ``Attributes``
section of the module docstring, or in an inline docstring immediately
following the variable.
Either form is acceptable, but the two should not be mixed. Choose
one convention to document module level variables and be consistent
with it.
Writing only because I haven't seen this option in the answers so far:
You can also define your constants as functions that simply return the desired constant value when called, so for example:
def get_const_my_const() -> str:
"""Returns 'my_const'."""
return "my_const"
This way they'll be a bit "more constant" on one hand (less worrying about reassignment) and they'll also provide the opportunity for regular documentation, as with any other function.
Lets say I import a module. In order for me to make the best use of it, I would like to know what properties, methods, etc. that I can use. Is there a way to find that out?
As an example: Determining running programs in Python
In this line:
os.system('WMIC /OUTPUT:C:\ProcessList.txt PROCESS get Caption,Commandline,Processid')
Let's say I wanted to also print out the memory consumed by the processes. How do I find out if that's possible? And what would be the correct 'label' for it? (just as the author uses 'Commandline', 'ProcessId')
Similarly, in this:
import win32com.client
def find_process(name):
objWMIService = win32com.client.Dispatch("WbemScripting.SWbemLocator")
objSWbemServices = objWMIService.ConnectServer(".", "root\cimv2")
colItems = objSWbemServices.ExecQuery(
"Select * from Win32_Process where Caption = '{0}'".format(name))
return len(colItems)
print find_process("SciTE.exe")
How would I make the function also print out the memory consumed, the executable path, etc.?
As for Python modules, you can do
>>> import module
>>> help(module)
and you'll get a list of supported methods (more exactly, you get the docstring, which might not contain every single method). If you want that, you can use
>>> dir(module)
although now you'd just get a long list of all properties, methods, classes etc. in that module.
In your first example, you're calling an external program, though. Of course Python has no idea which features wmic.exe has. How should it?
dir(module) returns the names of the attributes of the module
module.__dict__ is the mapping between the keys and the attributes objects themselves
module.__dict__.keys() and dir(module) are lists having the same elements, though they are not equals because the elements aren't in same order in them
it seems that help(module) iswhat you really need
Python has a build in function called dir(). I'm not sure if this is what you are referring to, but fire up a interactive python console and type:
import datetime
dir(datetime)
This should give you a list of methods, properties and submodules
#ldmvcd
Ok, excuse me, I think you are a beginner and you don't see to what fundamental notions I am refering.
Objects are Python’s abstraction for
data. All data in a Python program is
represented by objects or by relations
between objects.
http://docs.python.org/reference/datamodel.html#the-standard-type-hierarchy
I don't understand why it is called "abstraction": for me an object is something real in the machine, a series of bits organized according certain rules to represent conceptual data or functionning.
Names refer to objects. Names are
introduced by name binding operations.
Each occurrence of a name in the
program text refers to the binding of
that name established in the innermost
function block containing the use.
http://docs.python.org/reference/executionmodel.html#naming-and-binding
.
A namespace is a mapping from names to
objects. Most namespaces are currently
implemented as Python dictionaries,
but that’s normally not noticeable in
any way (except for performance), and
it may change in the future. Examples
of namespaces are: the set of built-in
names (containing functions such as
abs(), and built-in exception names);
the global names in a module; and the
local names in a function invocation.
In a sense the set of attributes of an
object also form a namespace.
http://docs.python.org/tutorial/classes.html#a-word-about-names-and-objects
.
By the way, I use the word attribute
for any name following a dot — for
example, in the expression z.real,
real is an attribute of the object z.
Strictly speaking, references to names
in modules are attribute references:
in the expression modname.funcname,
modname is a module object and
funcname is an attribute of it. In
this case there happens to be a
straightforward mapping between the
module’s attributes and the global
names defined in the module: they
share the same namespace!
http://docs.python.org/tutorial/classes.html#a-word-about-names-and-objects
.
Namespaces are created at different
moments and have different lifetimes.
http://docs.python.org/tutorial/classes.html#a-word-about-names-and-objects
.
The namespace for a module is
automatically created the first time a
module is imported. The main module
for a script is always called
main. http://docs.python.org/reference/executionmodel.html#naming-and-binding
.
Well, a Python programm is a big machine that plays with objects, references to these objects , names of these objects, and namespaces in which are binded the names and the objects , namespaces being implemented as dictionaries.
So, you're right: when I refer to keys , I refer to names being the keys in the diverse namespaces. Names are arbitrary or not , according if the objects they have been created to name are user's objects or built-in objects.
I give advise you to read thoroughly the parts
3.1. Objects , values and types
http://docs.python.org/reference/datamodel.html#the-standard-type-hierarchy
and
4.1. Naming and binding
http://docs.python.org/reference/executionmodel.html#naming-and-binding
I just posted below query to comp.lang.python, but i feel this kind of question has some kind of right-of-way here on Stack Overflow, too, so be it repeated. the essence: why does ‘builtins’ have two distinct interpretations in Python 3?
I would be very gladly accept any commentaries about what this
sentence, gleaned from http://celabs.com/python-3.1/reference/executionmodel.html,
is meant to mean, or why gods have decided this is the way to go. i
anticipate this guy named Kay Schluehr will have a say on that, or
maybe even the BDFL will care to pronounce __builtins__ the
correct way to his fallovers, followers, and fellownerds::
The built-in namespace associated with the execution of
a code block is actually found by looking up the name
__builtins__ in its global namespace; this should be a
dictionary or a module (in the latter case the module’s
dictionary is used). By default, when in the __main__
module, __builtins__ is the built-in module builtins;
when in any other module, __builtins__ is an alias for
the dictionary of the builtins module itself.
__builtins__ can be set to a user-created dictionary to
create a weak form of restricted execution.
it used to be the case that there were at least two distinct terms,
‘builtin’ (in the singular) and ‘builtins’ (in the plural), some of
which existed both in module and in dict form (?just guessing?). now
there is only builtins, so fortunately the ambivalence between
singular and plural has gone—good riddance.
but why does __builtins__ change its meaning depending on whether
this is the scope of the ‘script’ (i.e. the module whose name was
present, when calling python foobar.py) or whether this is the
scope of a secondary module (imported or executed, directly or
indirectly, by foobar.py)? i cannot understand the reasoning
behind this and find it highly confusing.
rationale: why do i care?—i want to be able to ‘export names to the
global namespace that were not marked private (by an underscore
prefix) in a python module that i execute via exec( compile( get
( locator ), locator, 'exec' ), R ) where R is supposed to going
to hold the private names of said module’. it is a little arcane but
the basic exercise is to by-pass python’s import system and get similr
results... it is all about injecting names into the all-global and the
module-global namespaces.
getattr(__builtins__, '__dict__', __builtins__) should give you the dict that you want to update to "export names to the global namespace", whether __builtins__ is a dict (then it doesn't have a __dict__ attribute so getattr returns the third argument, which is the dict __builtins__ itself) or a module (then it does have that attribute and getattr returns it). This is the workaround. As to why Python's documented to work in a way requiring such a tangled workaround, I'd classify it as an unfortunate case of an implementation issue surfacing to user-visible (and indeed documented) level (sigh). Pity we didn't think of fixing it in the move to Python 3, but it's too late to make backwards-incompatible changes now:-(.