["python"]
Docstring for variable

Is it posible to use docstring for plain variable? For example I have module called t def f(): """f""" l = lambda x: x """l""" and I do >>> import t >>> t.f.__doc__ 'f' but >>> t.l.__doc__ >>> Example is similar to PEP 258's (search for "this is g").
Use typing.Annotated to provide a docstring for variables. I originally wrote an answer (see below) where I said this wasn't possible. That was true back in 2012 but Python has moved on. Today you can provide the equivalent of a docstring for a global variable or an attribute of a class or instance. You will need to be running at least Python 3.9 for this to work: from __future__ import annotations from typing import Annotated Feet = Annotated[float, "feet"] Seconds = Annotated[float, "seconds"] MilesPerHour = Annotated[float, "miles per hour"] day: Seconds = 86400 legal_limit: Annotated[MilesPerHour, "UK national limit for single carriageway"] = 60 current_speed: MilesPerHour def speed(distance: Feet, time: Seconds) -> MilesPerHour: """Calculate speed as distance over time""" fps2mph = 3600 / 5280 # Feet per second to miles per hour return distance / time * fps2mph You can access the annotations at run time using typing.get_type_hints(): Python 3.9.1 (default, Jan 19 2021, 09:36:39) [Clang 10.0.1 (clang-1001.0.46.4)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import calc >>> from typing import get_type_hints >>> hints = get_type_hints(calc, include_extras=True) >>> hints {'day': typing.Annotated[float, 'seconds'], 'legal_limit': typing.Annotated[float, 'miles per hour', 'UK national limit for single carriageway'], 'current_speed': typing.Annotated[float, 'miles per hour']} Extract information about variables using the hints for the module or class where they were declared. Notice how the annotations combine when you nest them: >>> hints['legal_limit'].__metadata__ ('miles per hour', 'UK national limit for single carriageway') >>> hints['day'] typing.Annotated[float, 'seconds'] It even works for variables that have type annotations but have not been assigned a value. If I tried to reference calc.current_speed I would get an attribute error but I can still access its metadata: >>> hints['current_speed'].__metadata__ ('miles per hour',) The type hints for a module only include the global variables, to drill down you need to call get_type_hints() again on functions or classes: >>> get_type_hints(calc.speed, include_extras=True) {'distance': typing.Annotated[float, 'feet'], 'time': typing.Annotated[float, 'seconds'], 'return': typing.Annotated[float, 'miles per hour']} I only know of one tool so far that can use typing.Annotated to store documentation about a variable and that is Pydantic. It is slightly more complicated than just storing a docstring though it actually expects an instance of pydantic.Field. Here's an example: from typing import Annotated import typing_extensions from pydantic import Field from pydantic.main import BaseModel from datetime import date # TypeAlias is in typing_extensions for Python 3.9: FirstName: typing_extensions.TypeAlias = Annotated[str, Field( description="The subject's first name", example="Linus" )] class Subject(BaseModel): # Using an annotated type defined elsewhere: first_name: FirstName = "" # Documenting a field inline: last_name: Annotated[str, Field( description="The subject's last name", example="Torvalds" )] = "" # Traditional method without using Annotated # Field needs an extra argument for the default value date_of_birth: date = Field( ..., description="The subject's date of birth", example="1969-12-28", ) Using the model class: >>> guido = Subject(first_name='Guido', last_name='van Rossum', date_of_birth=date(1956, 1, 31)) >>> print(guido) first_name='Guido' last_name='van Rossum' date_of_birth=datetime.date(1956, 1, 31) Pydantic models can give you a JSON schema: >>> from pprint import pprint >>> pprint(Subject.schema()) {'properties': {'date_of_birth': {'description': "The subject's date of birth", 'example': '1969-12-28', 'format': 'date', 'title': 'Date Of Birth', 'type': 'string'}, 'first_name': {'default': '', 'description': "The subject's first name", 'example': 'Linus', 'title': 'First Name', 'type': 'string'}, 'last_name': {'default': '', 'description': "The subject's last name", 'example': 'Torvalds', 'title': 'Last Name', 'type': 'string'}}, 'required': ['date_of_birth'], 'title': 'Subject', 'type': 'object'} >>> If you use this class in a FastAPI application the OpenApi specification has example and description for all three of these taken from the relevant Field. And here's the original answer which was true back then but hasn't stood the test of time: No, it is not possible and it wouldn't be useful if you could. The docstring is always an attribute of an object (module, class or function), not tied to a specific variable. That means if you could do: t = 42 t.__doc__ = "something" # this raises AttributeError: '__doc__' is read-only you would be setting the documentation for the integer 42 not for the variable t. As soon as you rebind t you lose the docstring. Immutable objects such as numbers of strings sometimes have a single object shared between different users, so in this example you would probably actually have set the docstring for all occurences of 42 throughout your program. print(42 .__doc__) # would print "something" if the above worked! For mutable objects it wouldn't necessarily be harmful but would still be of limited use if you rebind the object. If you want to document an attribute of a class then use the class's docstring to describe it.