Special Variables

1.13. Special Variables#

Python’s special variables, often known as “magic” variables or “dunder” (double underscore) variables, play a crucial role in the language. These variables are distinguished by having double underscores (__) at the beginning and end of their names. They provide metadata about the code and control various aspects of the behavior of modules, classes, and functions.

The primary purposes of these special variables include:

Providing Metadata: Special variables often store important information about the module or object they are associated with. This metadata can include the module’s name, the file path of the script, and documentation strings, among other things.
Controlling Behavior: These variables can influence how modules and classes behave. For example, the __name__ variable determines whether a module is being run as the main program or being imported, which can affect how the code is executed.

Understanding and utilizing these special variables can help you write more robust and maintainable Python programs. They allow for greater introspection and control, enabling developers to write code that is more dynamic and flexible.

Here are some of the most commonly used special variables in Python:

1.13.1. `name`#

Description: Represents the module’s name.
Detailed Explanation: The __name__ variable is a built-in variable that provides the name of the current module. When a Python script is run, the interpreter sets this variable. If the module is executed directly (for example, by running python script.py), the __name__ variable is set to "__main__". If the module is imported into another module, __name__ is set to the name of the module (without the .py extension). This allows developers to write code that can behave differently depending on how it is executed.
Usage: Commonly used to check if the module is being run directly or being imported. This is useful for running code that should only execute when the script is run directly, such as tests or command-line interfaces.

Example:

if __name__ == "__main__":
    print("This script is being run directly")
    # Code to execute when the module is run directly
else:
    print("This script is being imported")
    # Code to execute when the module is imported

1.13.2. `file`#

Description: Holds the path of the currently executing script.
Detailed Explanation: The __file__ variable contains the path of the file from which the module is loaded. This can be either an absolute or a relative path, depending on how the script is run. It is particularly useful for determining the directory of the script, which can be helpful when working with file I/O operations, especially when you need to load resources that are in the same directory as the script.
Usage: Useful for finding the script’s location, which can be important for file handling, debugging, and setting up file paths relative to the script’s directory.

Example:

import os

script_path = __file__
script_dir = os.path.dirname(script_path)
print(f"Script path: {script_path}")
print(f"Script directory: {script_dir}")

1.13.3. `doc`#

Description: Contains the documentation string of a module, class, method, or function.
Detailed Explanation: The __doc__ variable holds the docstring (documentation string) of the object it is associated with. Docstrings are string literals that appear right after the definition of a module, class, method, or function. They are used to document the purpose and usage of the object. Python’s built-in help() function uses these docstrings to provide help information.
Usage: Allows for the inclusion and retrieval of documentation within the code. It’s helpful for understanding what a particular piece of code does without needing to look up external documentation. It promotes self-documenting code, which is easier to maintain and understand.

Example:

def example():
    """This is an example function."""
    pass

print(example.__doc__)
# Output: This is an example function.

1.13.4. `package`#

Description: Denotes the module’s package name.
Detailed Explanation: The __package__ variable is used to define the package name in which a module resides. This is important for the module’s import system. When a module is part of a package, __package__ is set to the package name. If the module is a top-level module (i.e., not part of any package), __package__ is set to None. The primary use of __package__ is to resolve relative imports. Relative imports use a module’s __package__ attribute to determine the location of the module in the package hierarchy.
Usage: Assists in organizing modules within a package. When running a module as a script, it helps in resolving relative imports by providing the package context.

Example:

print(__package__)
# If the module is part of a package, this will output the package name.
# If the module is a top-level module, this will output None.

1.13.5. `annotations`#

Description: Stores annotations for variables, parameters, and return types.
Detailed Explanation: The __annotations__ attribute is a dictionary that stores type hints for function parameters and return types. Type hints provide a way to indicate the expected types of variables, function parameters, and return values. They do not enforce type checking at runtime but can be used by static analysis tools and IDEs to improve code readability and detect potential type-related errors.
Usage: Used for providing type hints and metadata, which can be useful for type checking, improving code readability, and aiding in the development process by providing more information about the expected types of variables and function parameters.

Example:

def func(x: int, y: str) -> str:
    return y * x

print(func.__annotations__)
# Output: {'x': <class 'int'>, 'y': <class 'str'>, 'return': <class 'str'>}

1.13.6. `path`#

Description: In package modules, it holds a list of strings that specify the search path for modules.
Detailed Explanation: The __path__ attribute is used in package modules to define the list of directories that the interpreter will search for submodules and subpackages. This attribute is typically a list containing a single string: the directory containing the package. However, it can be modified to include additional directories, allowing for greater flexibility in module organization and module loading.
Usage: Crucial for defining search paths in package modules, especially for large projects with complex directory structures. It helps the interpreter locate and load submodules within a package.

Example:

import mypackage

print(mypackage.__path__)
# Output: ['/path/to/mypackage']

1.13.7. `cached`#

Description: Holds the path to the compiled version of the module.
Detailed Explanation: The __cached__ attribute contains the path to the compiled bytecode file of the module, typically stored in the __pycache__ directory. This attribute is useful for debugging and optimizing module imports, as it provides a way to locate the compiled version of the module, which can be loaded more quickly than the source code.
Usage: Useful for debugging and optimizing module imports, as it indicates where the bytecode of the module is stored, which can help in performance analysis and troubleshooting.

Example:

import mymodule

print(mymodule.__cached__)
# Output: '/path/to/mymodule.cpython-38.pyc'

1.13.8. `loader`#

Description: Refers to the loader that imported the module.
Detailed Explanation: The __loader__ attribute references the loader object that was responsible for loading the module. The loader is part of Python’s import system and is responsible for locating, loading, and initializing modules. This attribute provides information about the module’s loader, which can be useful for debugging import issues and understanding the module loading process.
Usage: Provides information about the module’s loader, which is responsible for loading the module’s code. This can be useful for understanding and troubleshooting the module import process.

Example:

import mymodule

print(mymodule.__loader__)
# Output: <SourceFileLoader object>

1.13.9. `spec`#

Description: Contains the module specification, an instance of importlib.machinery.ModuleSpec.
Detailed Explanation: The __spec__ attribute holds the module specification, which is an instance of the importlib.machinery.ModuleSpec class. The module specification contains detailed information about the module, including its name, loader, origin, and submodule search locations. This attribute is part of Python’s import system and provides a standardized way to store and access module metadata.
Usage: Provides detailed information about the module, including its loader, origin, and submodule search locations. This can be useful for introspection, debugging, and understanding the module’s structure and dependencies.

Example:

import mymodule

print(mymodule.__spec__)
# Output: ModuleSpec(name='mymodule', loader=<_frozen_importlib_external.SourceFileLoader object>)

1.13.10. `builtins`#

Description: Contains a reference to the built-in namespace.
Detailed Explanation: The __builtins__ attribute provides access to the built-in namespace, which includes built-in functions (e.g., len(), print()), exceptions (e.g., ValueError, TypeError), and other built-in objects. This attribute is available in all modules and allows access to Python’s built-in functions and variables without needing to import them explicitly.
Usage: Provides access to Python’s built-in functions and variables, which are available in all modules without needing to import them. This attribute is useful for introspection and understanding the built-in functionality available in Python.

Example:

print(dir(__builtins__))
# Output: List of all built-in functions, exceptions, and other built-in objects

1.13.11. `import`#

Description: A special function used to import modules.
Detailed Explanation: The __import__ function is a built-in function that can be used to import modules dynamically. It allows for more flexibility in module imports, as the module name can be provided as a string, enabling conditional imports and imports based on runtime conditions. This function is the underlying implementation of the import statement.
Usage: Allows for dynamic importing of modules. This can be useful when the module name is stored in a string or when importing modules conditionally based on runtime logic.

Example:

math = __import__('math')
print(math.sqrt(4))
# Output: 2.0

1.13.12. `dict`#

Description: Contains the namespace supporting arbitrary function and variable names.
Detailed Explanation: The __dict__ attribute is a dictionary that contains the object’s namespace. For modules, classes, and instances, this attribute provides a dictionary representation of their attributes and methods. It is useful for accessing and modifying an object’s attributes dynamically.
Usage: Useful for accessing the internal attributes of objects. It provides a dictionary representation of an object’s attributes, allowing for introspection and dynamic modification of attributes.

Example:

class MyClass:
    a = 10
    b = 20

print(MyClass.__dict__)
# Output: {'__module__': '__main__', 'a': 10, 'b': 20, '__dict__': <attribute '__dict__' of 'MyClass' objects>, '__weakref__': <attribute '__weakref__' of 'MyClass' objects>, '__doc__': None}

1.13.13. `class`#

Description: References the class of an instance.
Detailed Explanation: The __class__ attribute provides a reference to the class of an instance. This attribute is useful for determining the type of an instance at runtime, which can be important for type checking, debugging, and implementing dynamic behavior based on the instance’s class.
Usage: Useful for determining the type of an instance, especially in debugging or dynamic type checking. It allows for introspection of an object’s class.

Example:

obj = MyClass()
print(obj.__class__)
# Output: <class '__main__.MyClass'>

1.13.14. `all`#

Description: A list of public objects of a module.
Detailed Explanation: The __all__ attribute is a list that defines the public interface of a module. When from module import * is used, only the names listed in __all__ will be imported. This attribute helps control the public API of the module, specifying which attributes and functions should be exposed to users of the module.
Usage: Specifies which attributes should be imported when from module import * is used. This helps control the public API of the module, making it clear which parts of the module are intended for external use.

Example:

__all__ = ['func1', 'func2']

def func1():
    pass

def func2():
    pass

def func3():
    pass

# When using `from module import *`, only func1 and func2 will be imported.

Table 1.5 Special Variables in Python and Their Descriptions#
Variable	Description
`__name__`	Indicates whether the module is run as the main program or imported.
`__file__`	Stores the path to the currently executing script.
`__doc__`	Contains the documentation string of a module, class, method, or function.
`__package__`	Denotes the module’s package name.
`__annotations__`	Holds type hints for variables, parameters, and return types.
`__path__`	Specifies the search path for modules in a package.
`__cached__`	Contains the path to the compiled bytecode file of the module.
`__loader__`	Refers to the loader that imported the module.
`__spec__`	Contains the module specification.
`__builtins__`	Provides access to Python’s built-in functions and variables.
`__import__`	A function used to import modules dynamically.
`__dict__`	Contains the namespace supporting arbitrary function and variable names.
`__class__`	References the class of an instance.
`__all__`	Lists public objects of a module.

Special Variables

Contents

1.13. Special Variables#

1.13.1. __name__#

1.13.2. __file__#

1.13.3. __doc__#

1.13.4. __package__#

1.13.5. __annotations__#

1.13.6. __path__#

1.13.7. __cached__#

1.13.8. __loader__#

1.13.9. __spec__#

1.13.10. __builtins__#

1.13.11. __import__#

1.13.12. __dict__#

1.13.13. __class__#

1.13.14. __all__#

1.13.1. `name`#

1.13.2. `file`#

1.13.3. `doc`#

1.13.4. `package`#

1.13.5. `annotations`#

1.13.6. `path`#

1.13.7. `cached`#

1.13.8. `loader`#

1.13.9. `spec`#

1.13.10. `builtins`#

1.13.11. `import`#

1.13.12. `dict`#

1.13.13. `class`#

1.13.14. `all`#