Python

https://docs.python.org/3.9/
Admin
Python is an interpreted, high-level, general-purpose programming language designed to help...
Tokens:5,696,380
Snippets:40,236
Trust Score:10
Update:14 hours ago
Show doc for...
Tokens:
Raw
### Basic Setup file entry

Source: https://docs.python.org/3.9/install/index.html

Example of a Setup file line defining a module named 'foo' built from 'foomodule.c'. This is the starting point before adding any special libraries or flags.

```plaintext
foo foomodule.c
```

--------------------------------

### Distutils setup script example

Source: https://docs.python.org/3.9/distutils/setupscript.html

A complete setup script for the Distutils package, showing how to call setup() with metadata and a list of packages. It uses Unix-style slash-separated pathnames for portability.

```python
#!/usr/bin/env python

from distutils.core import setup

setup(name='Distutils',
      version='1.0',
      description='Python Distribution Utilities',
      author='Greg Ward',
      author_email='gward@python.net',
      url='https://www.python.org/sigs/distutils-sig/',
      packages=['distutils', 'distutils.command'],
     )
```

--------------------------------

### Incremental build and install: python setup.py build then install

Source: https://docs.python.org/3.9/install/index.html

Build everything in one step and install in a second step by invoking the setup script twice. The install command will first run the build command, which quickly notices nothing to do if the build directory is up-to-date.

```bash
python setup.py build
python setup.py install
```

--------------------------------

### setup() with dependency metadata and download_url

Source: https://docs.python.org/3.9/whatsnew/2.5.html

Example of using the new setup() keyword parameters requires, obsoletes, and download_url to record dependency information in PKG-INFO when building a source distribution with sdist.

```python
VERSION = '1.0'
setup(name='PyPackage',
      version=VERSION,
      requires=['numarray', 'zlib (>=1.1.4)'],
      obsoletes=['OldPackage']
      download_url=('http://www.example.com/pypackage/dist/pkg-%s.tar.gz'
                    % VERSION),
     )
```

--------------------------------

### files('wheel') example

Source: https://docs.python.org/3.9/library/importlib.metadata.html

Shows how to get the full set of files installed by a distribution using the files() function. Each file object is a PackagePath with dist, size, and hash properties.

```python
>>> util = [p for p in files('wheel') if 'util.py' in str(p)][0]  
>>> util  
PackagePath('wheel/util.py')
>>> util.size  
859
>>> util.dist  
<importlib.metadata._hooks.PathDistribution object at 0x101e0cef0>
>>> util.hash  
<FileHash mode: sha256 value: bYkw5oMccfazVCoYQwKkkemoVyMAFoR34mmKBx8R1NI>
```

--------------------------------

### Install a distutils-based module on Windows

Source: https://docs.python.org/3.9/install/index.html

Run this command from a command prompt window (Start ‣ Accessories) to build and install a module distribution on Windows.

```bash
setup.py install
```

--------------------------------

### Using importlib.metadata to read package metadata

Source: https://docs.python.org/3.9/whatsnew/3.8.html

Example showing how to use importlib.metadata to get the version, requirements, and files of an installed package. Requires the 'requests' package to be installed.

```python
>>> # Note following example requires that the popular "requests"
>>> # package has been installed.
>>>
>>> from importlib.metadata import version, requires, files
>>> version('requests')
'2.22.0'
>>> list(requires('requests'))
['chardet (<3.1.0,>=3.0.2)']
>>> list(files('requests'))[:5]
[PackagePath('requests-2.22.0.dist-info/INSTALLER'),
 PackagePath('requests-2.22.0.dist-info/LICENSE'),
 PackagePath('requests-2.22.0.dist-info/METADATA'),
 PackagePath('requests-2.22.0.dist-info/RECORD'),
 PackagePath('requests-2.22.0.dist-info/WHEEL')]
```

--------------------------------

### setup()

Source: https://docs.python.org/3.9/library/turtle.html

Sets the size and position of the main window.

```APIDOC
## setup()

### Description
Sets the size and position of the main window.

### Method
Function call

### Endpoint
setup(width=_CFG['width'], height=_CFG['height'], startx=_CFG['leftright'], starty=_CFG['topbottom'])

### Parameters
- width (int) - Optional - Width of the window in pixels or a fraction of the screen.
- height (int) - Optional - Height of the window in pixels or a fraction of the screen.
- startx (int) - Optional - Starting x coordinate of the window.
- starty (int) - Optional - Starting y coordinate of the window.

### Response
No return value.
```

--------------------------------

### GET Request Example

Source: https://docs.python.org/3.9/library/http.client.html

Example session using the GET method with http.client, including reading the entire response and reading in chunks.

```APIDOC
## GET Request Example

### Description
Example session using the GET method with http.client, including reading the entire response and reading in chunks.

### Method
GET

### Endpoint
/

### Parameters
None

### Request Example
```python
conn = http.client.HTTPSConnection("www.python.org")
conn.request("GET", "/")
```

### Response
#### Success Response (200)
- **status** (int) - HTTP status code
- **reason** (str) - Reason phrase
- **data** (bytes) - Response body

#### Response Example
```python
>>> r1 = conn.getresponse()
>>> print(r1.status, r1.reason)
200 OK
>>> data1 = r1.read()
```
```

--------------------------------

### Simple setup.py for building an extension module

Source: https://docs.python.org/3.9/extending/building.html

A minimal setup.py that defines an extension named 'demo' from a single source file 'demo.c'. Running 'python setup.py build' compiles the extension and places it in the build directory.

```python
from distutils.core import setup, Extension

module1 = Extension('demo',
                    sources = ['demo.c'])

setup (name = 'PackageName',
       version = '1.0',
       description = 'This is a demo package',
       ext_modules = [module1])
```

--------------------------------

### descriptions example: get group descriptions

Source: https://docs.python.org/3.9/library/nntplib.html

Shows how to call s.descriptions() with a wildmat pattern to get a dictionary of group descriptions. The example uses an existing NNTP connection object s.

```python
>>> resp, descs = s.descriptions('gmane.comp.python.*')
>>> len(descs) 
295
>>> descs.popitem() 
('gmane.comp.python.bio.general', 'BioPython discussion list (Moderated)')
```

--------------------------------

### setup.py for C extension

Source: https://docs.python.org/3.9/whatsnew/2.0.html

An example setup.py script for a C extension, taken from the PyXML package. It defines an Extension object with macros, include directories, and sources, then passes it to setup() via ext_modules.

```python
from distutils.core import setup, Extension

expat_extension = Extension('xml.parsers.pyexpat',
     define_macros = [('XML_NS', None)],
     include_dirs = [ 'extensions/expat/xmltok',
                      'extensions/expat/xmlparse' ],
     sources = [ 'extensions/pyexpat.c',
                 'extensions/expat/xmltok/xmltok.c',
                 'extensions/expat/xmltok/xmlrole.c', ]
       )
setup (name = "PyXML", version = "0.5.4",
       ext_modules =[ expat_extension ] )

```

--------------------------------

### Using multiprocessing.Pool for parallel function execution

Source: https://docs.python.org/3.9/library/multiprocessing.html

Demonstrates the Pool class with apply_async, map, imap, and timeout handling. The example starts 4 worker processes and shows how to get results asynchronously, map a function over a range, and handle a TimeoutError when a task exceeds the timeout.

```python
from multiprocessing import Pool
import time

def f(x):
    return x*x

if __name__ == '__main__':
    with Pool(processes=4) as pool:         # start 4 worker processes
        result = pool.apply_async(f, (10,)) # evaluate "f(10)" asynchronously in a single process
        print(result.get(timeout=1))        # prints "100" unless your computer is *very* slow

        print(pool.map(f, range(10)))       # prints "[0, 1, 4,..., 81]"

        it = pool.imap(f, range(10))
        print(next(it))                     # prints "0"
        print(next(it))                     # prints "1"
        print(it.next(timeout=1))           # prints "4" unless your computer is *very* slow

        result = pool.apply_async(time.sleep, (10,))
        print(result.get(timeout=1))        # raises multiprocessing.TimeoutError
```

--------------------------------

### Use patch start and stop in setUp and tearDown

Source: https://docs.python.org/3.9/library/unittest.mock-examples.html

Alternative to class decorators: start the patch in setUp and stop it in tearDown. The mock is stored as an instance attribute. Ensure stop is called to undo the patch.

```python
>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         self.patcher = patch('mymodule.foo')
...         self.mock_foo = self.patcher.start()
...
...     def test_foo(self):
...         self.assertIs(mymodule.foo, self.mock_foo)
...
...     def tearDown(self):
...         self.patcher.stop()
...
>>> MyTest('test_foo').run()
```

--------------------------------

### setup.py data_files example

Source: https://docs.python.org/3.9/distutils/setupscript.html

Shows the syntax for specifying data_files as a sequence of (directory, files) pairs. Each file name is relative to the setup.py script. The directory is relative to the installation prefix, and absolute paths are discouraged due to wheel incompatibility.

```python
setup(...,
      data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                  ('config', ['cfg/data.cfg'])],
     )
```

--------------------------------

### Multiple patches in setUp and tearDown

Source: https://docs.python.org/3.9/library/unittest.mock.html

Typical use case for multiple patches in a TestCase's setUp and tearDown methods. Each patcher is started in setUp and stopped in tearDown.

```python
>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         self.patcher1 = patch('package.module.Class1')
...         self.patcher2 = patch('package.module.Class2')
...         self.MockClass1 = self.patcher1.start()
...         self.MockClass2 = self.patcher2.start()
...
...     def tearDown(self):
...         self.patcher1.stop()
...         self.patcher2.stop()
...
...     def test_something(self):
...         assert package.module.Class1 is self.MockClass1
...         assert package.module.Class2 is self.MockClass2
...
>>> MyTest('test_something').run()
```

--------------------------------

### Windows install: cd and python setup.py install

Source: https://docs.python.org/3.9/install/index.html

For Windows, after unpacking the archive to C:\Temp\foo-1.0, open a command prompt and run these commands.

```bash
cd c:\Temp\foo-1.0
python setup.py install
```

--------------------------------

### PyUnicodeDecodeError_GetStart, PyUnicodeEncodeError_GetStart, PyUnicodeTranslateError_GetStart

Source: https://docs.python.org/3.9/c-api/exceptions.html

Get the start attribute of the given exception object and place it into *start. start must not be NULL. Return 0 on success, -1 on failure.

```APIDOC
## PyUnicodeDecodeError_GetStart, PyUnicodeEncodeError_GetStart, PyUnicodeTranslateError_GetStart

### Description
Get the start attribute of the given exception object and place it into *start. start must not be NULL. Return 0 on success, -1 on failure.

### Signatures
- int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
- int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
- int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)

### Parameters
- **exc** (PyObject*) - Required - The exception object.
- **start** (Py_ssize_t*) - Required - Pointer to where the start attribute will be stored. Must not be NULL.

### Return Value
- **int** - 0 on success, -1 on failure.

```

--------------------------------

### Using timeit.timeit() with setup

Source: https://docs.python.org/3.9/library/timeit.html

Demonstrates the timeit.timeit() function with a setup string. The output shows the time in seconds for each statement.

```python
>>> import timeit
>>> timeit.timeit('char in text', setup='text = "sample string"; char = "g"')
0.41440500499993504
>>> timeit.timeit('text.find(char)', setup='text = "sample string"; char = "g"')
1.7246671520006203
```

--------------------------------

### Check launcher availability with py

Source: https://docs.python.org/3.9/using/windows.html

Run this command in Command Prompt to verify the launcher is installed and start the latest installed Python version. If not installed, an error message is shown.

```command
py
```

--------------------------------

### Instantiate Path with 'setup.py'

Source: https://docs.python.org/3.9/library/pathlib.html

Shows creating a Path object for 'setup.py', which returns a PosixPath on a POSIX system.

```python
>>> Path('setup.py')
PosixPath('setup.py')
```

--------------------------------

### Install python-dev on Debian

Source: https://docs.python.org/3.9/faq/extending.html

Run apt-get install python-dev to get necessary files for compiling Python extensions on Debian systems.

```bash
apt-get install python-dev
```

--------------------------------

### Setup script with one extension using ext_modules

Source: https://docs.python.org/3.9/distutils/setupscript.html

A complete setup script that imports setup and Extension from distutils.core and defines a distribution with a single extension module 'foo'.

```python
from distutils.core import setup, Extension
setup(name='foo',
      version='1.0',
      ext_modules=[Extension('foo', ['foo.c'])],
      )
```

--------------------------------

### Create enum with start parameter

Source: https://docs.python.org/3.9/whatsnew/3.5.html

The Enum callable now accepts a start parameter to specify the initial number of enum values when only names are provided. The example shows creating an enum with values starting at 10.

```python
>>> Animal = enum.Enum('Animal', 'cat dog', start=10)
>>> Animal.cat
<Animal.cat: 10>
>>> Animal.dog
<Animal.dog: 11>
```

--------------------------------

### EnvBuilder.setup_scripts(context)

Source: https://docs.python.org/3.9/library/venv.html

Installs activation scripts appropriate to the platform into the virtual environment.

```APIDOC
## EnvBuilder.setup_scripts(context)

### Description
Installs activation scripts appropriate to the platform into the virtual environment.

### Method
setup_scripts

### Parameters
- **context** (object) - Required - The context object representing the virtual environment.

### Notes
- On Windows, in version 3.7.2, this method was responsible for copying the redirector scripts; in 3.7.3, that responsibility moved to setup_python().
```

--------------------------------

### setup.py for building custom extension

Source: https://docs.python.org/3.9/extending/newtypes_tutorial.html

Uses distutils to build the custom extension from custom.c.

```python
from distutils.core import setup, Extension
setup(name="custom", version="1.0",
      ext_modules=[Extension("custom", ["custom.c"])])
```

--------------------------------

### Python comments example

Source: https://docs.python.org/3.9/tutorial/introduction.html

Shows how comments are written in Python: starting with #, they can appear at the start of a line or after code, but a hash inside a string literal is not a comment.

```python
# this is the first comment
spam = 1  # and this is the second comment
          # ... and now a third!
text = "# This is not a comment because it's inside quotes."
```

--------------------------------

### curses.setupterm

Source: https://docs.python.org/3.9/genindex-all.html

Initializes the terminal.

```APIDOC
## curses.setupterm

### Description
Initializes the terminal.

### Method
- (module function)

### Parameters
- **term** (str) - Optional - The terminal name.
- **fd** (int) - Optional - The file descriptor.

### Returns
None

### Source
[Python 3.9 documentation](https://docs.python.org/3.9/library/curses.html#curses.setupterm)
```

--------------------------------

### enumerate() usage examples

Source: https://docs.python.org/3.9/library/functions.html

Shows how to use enumerate() with a list, with and without the start parameter. The output demonstrates the default start of 0 and the effect of start=1.

```python
>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
>>> list(enumerate(seasons))
[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
>>> list(enumerate(seasons, start=1))
[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]
```

--------------------------------

### turtle.Screen.setup() window size and position examples

Source: https://docs.python.org/3.9/library/turtle.html

Shows two calls to screen.setup(): one setting the window to 200x200 pixels at the upper left, and another setting it to 75% of screen width by 50% of screen height and centering. The comments explain the effect of each call.

```python
>>> screen.setup (width=200, height=200, startx=0, starty=0)
>>>              # sets window to 200x200 pixels, in upper left of screen
>>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
>>>              # sets window to 75% of screen by 50% of screen and centers
```

--------------------------------

### Path.open example

Source: https://docs.python.org/3.9/library/pathlib.html

Opens the file pointed to by the path like the built-in open() function. The example shows reading the first line of 'setup.py'.

```python
>>> p = Path('setup.py')
>>> with p.open() as f:
...     f.readline()
...
'#!/usr/bin/env python3\n'
```

--------------------------------

### Install python-devel RPM on Red Hat

Source: https://docs.python.org/3.9/faq/extending.html

Install the python-devel RPM to get necessary files for compiling Python extensions on Red Hat systems.

```bash
python-devel
```

--------------------------------

### TestCase with setUp method

Source: https://docs.python.org/3.9/library/unittest.html

Uses setUp to create a widget instance for each test, reducing repetitive setup. Includes two test methods that verify default size and resize behavior.

```python
import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def test_default_widget_size(self):
        self.assertEqual(self.widget.size(), (50,50),
                         'incorrect default size')

    def test_widget_resize(self):
        self.widget.resize(100,150)
        self.assertEqual(self.widget.size(), (100,150),
                         'wrong size after resize')
```

--------------------------------

### Install Python 2.5.1 on OpenBSD i386

Source: https://docs.python.org/3.9/using/unix.html

Example for i386 users on OpenBSD 4.2 to install Python 2.5.1p2 using a direct FTP package URL.

```shell
pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/i386/python-2.5.1p2.tgz
```

--------------------------------

### setUp()

Source: https://docs.python.org/3.9/library/unittest.html

Method called to prepare the test fixture. Called immediately before the test method.

```APIDOC
## setUp()

### Description
Method called to prepare the test fixture. This is called immediately before calling the test method. Any exception raised by this method, other than AssertionError or SkipTest, will be considered an error rather than a test failure. The default implementation does nothing.

### Method
`setUp()`

### Parameters
None

### Returns
None

```

--------------------------------

### itertools.islice() with slice object example

Source: https://docs.python.org/3.9/whatsnew/2.5.html

Shows creating a slice object and passing its start, stop, and step attributes to itertools.islice(), which now accepts None for start and step.

```python
s = slice(5)     # Create slice object
itertools.islice(iterable, s.start, s.stop, s.step)
```

--------------------------------

### test.support.modules_setup()

Source: https://docs.python.org/3.9/library/test.html

Returns a copy of sys.modules.

```APIDOC
## test.support.modules_setup()

### Description
Returns a copy of sys.modules.

### Returns
- A copy of sys.modules.
```

--------------------------------

### Create source distribution on Windows with setup.py sdist

Source: https://docs.python.org/3.9/distutils/introduction.html

On Windows, open a command prompt window and use this command instead of the python-prefixed version to create the source distribution.

```shell
setup.py sdist
```

--------------------------------

### find_longest_match example

Source: https://docs.python.org/3.9/library/difflib.html

Example usage of SequenceMatcher.find_longest_match to find the longest matching block between two strings. The output shows a Match object with start indices and size.

```python
>>> s = SequenceMatcher(None, " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
Match(a=0, b=4, size=5)
```

--------------------------------

### Setup file line structure

Source: https://docs.python.org/3.9/install/index.html

Shows the general structure of a line in a Setup file, which describes a single extension module. Each line contains the module name, source files, preprocessor arguments, and libraries.

```plaintext
module ... [sourcefile ...] [cpparg ...] [library ...]
```

--------------------------------

### distutils.core.Distribution

Source: https://docs.python.org/3.9/distutils/apiref.html

Describes how to build, install and package up a Python software package. It is created by the setup() function and accepts keyword arguments as listed in the setup() function documentation.

```APIDOC
## distutils.core.Distribution

### Description
A Distribution describes how to build, install and package up a Python software package. See the setup() function for a list of keyword arguments accepted by the Distribution constructor. setup() creates a Distribution instance.

### Constructor Parameters
Accepts the same keyword arguments as the setup() function. See the setup() function documentation for details.

### Notes
Changed in version 3.7: Distribution now warns if `classifiers`, `keywords` and `platforms` fields are not specified as a list or a string.
```
Tokens:
Raw