{"id":568,"date":"2021-01-08T15:23:58","date_gmt":"2021-01-08T20:23:58","guid":{"rendered":"https:\/\/www.alpharithms.com\/?p=568"},"modified":"2022-06-16T15:23:57","modified_gmt":"2022-06-16T19:23:57","slug":"python-__all__-variable","status":"publish","type":"post","link":"https:\/\/www.alpharithms.com\/python-__all__-variable-582315\/","title":{"rendered":"Understanding Python’s __all__ Variable"},"content":{"rendered":"

Python’s import system works very intuitively by design. Importing entire modules or single variables can be done with single-line syntax. For cases where the entirety of a package is being imported, a custom implementation of the __all__ variable can help restrict just what “all” really means.<\/p>\n

Python’s import system, in cadence with many other programming languages<\/a> import systems, allows for the use of the wildcard operator *. This instructs Python to import “all” of a module’s contents. By default, this includes functions<\/code>, Classes<\/code>, variables<\/code>, and everything else without a name prefixed with an underscore.<\/p>\n

Custom __all__ Implementation<\/h2>\n

The __all__<\/code> variable in Python is very intuitive to use but can be difficult to express in words. Let’s consider the following code:<\/p>\n

examples\/custom.py\r\n\r\n# Import a library\r\nimport random\r\n\r\n# Define constants\r\n__COLORS__ = (\"red\", \"blue\", \"yellow\", \"green\")\r\n__SHAPES__ = (\"round\", \"square\", \"cylindrical\")\r\n\r\n# Define a custom class\r\nclass Candy:\r\n    \"\"\"\r\n    An object model for a piece of candy expressing color and shape\r\n    \"\"\"\r\n    def __init__(self, color: str, shape: str):\r\n        self.color = color\r\n        self.shape = shape\r\n\r\n    def __str__(self):\r\n        return f\"A tasty piece of {self.shape} {self.color} candy\"\r\n\r\n# Define a custom function\r\ndef get_random_candy():\r\n    \"\"\"\r\n    Creates a random Candy object\r\n    Returns:\r\n        Candy object\r\n    \"\"\"\r\n    return Candy(random.choice(__COLORS__), random.choice(__SHAPES__))\r\n\r\n# Create a random piece of candy\r\nrandom_candy = get_random_candy()\r\n<\/pre>\n
This contrived selection of code defines a wide range of objects including variables<\/code>, Classes<\/code>, functions<\/code>, and even imports another package. Now, let’s consider the use of this file within another Python file:<\/p>\n
examples\/custom_two.py\r\n\r\n# Import everything from custom file\r\nfrom custom import *\r\n\r\n# Access variable\r\ncandy_1 = random_candy\r\n\r\n# Create new object using function\r\ncandy_2 = get_random_candy()\r\n\r\n# Create new object using Class\r\ncandy_3 = Candy('cyan', 'triangular')\r\n\r\n# Create new object using Class using protected constants\r\ncandy_4 = Candy(__COLORS__[0], __SHAPES__[1])\r\n\r\n# Access imported library\r\nrandom_number = random.choice([0, 1, 2, 3, 4])<\/pre>\n
This file accesses\u00a0everything<\/em> we created in our examples.py file initially. When we run this code, we encounter a snag when creating the candy_4 object<\/code>, which accesses the double-underscore prefixed variables:<\/p>\n
NameError: name '__COLORS__' is not defined<\/code><\/p>\n
This happens because Python does not implicitly import<\/a> anything prefixed with a underscore (including double underscores) by default. To ensure these objects are imported during wildcard import statements, modules must explicitly define them. To achieve this, we would add the following code to the examples\/custom.py<\/code> file:<\/p>\n
__all__ = ['__COLORS__', '__SHAPES__', 'Candy', 'get_random_candy', 'random_candy', 'random']<\/pre>\n
Now, when we run the code from our examples\/custom_two.py<\/code> file, there are no errors. This is because the __COLORS__<\/code> and __SHAPES__<\/code> constants were explicitly added to the module exports via the __all__<\/code> variable.<\/p>\n
Using __all__ to Explicitly Remove Import\/Exports<\/h2>\n
Python’s __all__<\/code> variable is useful to include underscore prefixed variables that would otherwise not be imported. However, this brings about a certain added level of responsibility for developers:\u00a0everything<\/em> intended for export must be explicitly added to the __all__<\/code> variable. That means leaving off a variable<\/code>, Class<\/code>, function<\/code>, or other form of object that would have been exported by default\u2014now results in that object not being exported. Consider the following code:<\/p>\n
__all__ = ['__COLORS__', '__SHAPES__', 'Candy', 'random_candy', 'random']<\/pre>\n
This now leads to a NameError<\/code> exception where we’re calling the get_random_candy()<\/code> function. Normally, during an import *<\/code> statement, function such as this one would be included by default. Since we’ve overwritten the default __all__<\/code> variable however\u2014anything not included won’t be imported!<\/p>\n
Final Thoughts<\/h2>\n
I am of the school that using from package import *<\/code> is rarely a good idea. As such, I find myself with very little need for use of this approach at customizing the __all__<\/code> variable. However, knowing what it is and how it\u00a0can<\/em> be used is helpful\u2014if for no other reason than to be able to digest Python projects which make heavier usage of this approach.<\/p>\n","protected":false},"excerpt":{"rendered":"
Python’s import system works very intuitively by design. Importing entire modules or single variables can be done with single-line syntax. For cases where the entirety of a package is being imported, a custom implementation of the __all__ variable can help restrict just what “all” really means. Python’s import system, in cadence with many other programming […]<\/p>\n","protected":false},"author":2,"featured_media":569,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"inline_featured_image":false,"footnotes":""},"categories":[655,10],"tags":[243,242,143,244],"acf":[],"_links":{"self":[{"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/posts\/568"}],"collection":[{"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/comments?post=568"}],"version-history":[{"count":1,"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/posts\/568\/revisions"}],"predecessor-version":[{"id":570,"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/posts\/568\/revisions\/570"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/media\/569"}],"wp:attachment":[{"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/media?parent=568"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/categories?post=568"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.alpharithms.com\/wp-json\/wp\/v2\/tags?post=568"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}