Python

https://docs.python.org/3.10
Admin
Python is a high-level, interpreted programming language that emphasizes readability and developer...
Tokens:2,618,514
Snippets:29,392
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Manage Multiple Patches in setUp and tearDown

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

This example demonstrates how to manage multiple patches within a unittest.TestCase's setUp and tearDown methods using start() and stop().

```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()
```

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

### Starting a Manager and Getting the Server

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

Demonstrates how to create a BaseManager, obtain its server object, and start the server to listen for connections.

```python
from multiprocessing.managers import BaseManager
manager = BaseManager(address=('', 50000), authkey=b'abc')
server = manager.get_server()
server.serve_forever()
```

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

### Providing Setup with Imports

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

Use the 'setup' parameter to import functions defined in your script into the timeit environment. The example defines and times a 'test' function.

```python
def test():
    """Stupid test function"""
    L = [i for i in range(100)]

if __name__ == '__main__':
    import timeit
    print(timeit.timeit("test()", setup="from __main__ import test"))
```

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

### Basic Process creation and execution

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

This is a minimal example of creating a `Process` object, starting it, and waiting for it to complete using `start()` and `join()`.

```Python
from multiprocessing import Process

def f(name):
    print('hello', name)

if __name__ == '__main__':
    p = Process(target=f, args=('bob',))
    p.start()
    p.join()

```

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

### Multiprocessing Pool Example Setup

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

Provides setup code for demonstrating the use of multiprocessing.Pool, including helper functions for task execution and error handling.

```python
import multiprocessing
import time
import random
import sys

#
# Functions used by test code
#

def calculate(func, args):
    result = func(*args)
    return '%s says that %s%s = %s' % (
        multiprocessing.current_process().name,
        func.__name__,
        args,
        result
        )

def calculatestar(args):
    return calculate(*args)

def mul(a, b):
    time.sleep(0.5 * random.random())
    return a * b

def plus(a, b):
    time.sleep(0.5 * random.random())
    return a + b

def f(x):
    return 1.0 / (x - 5.0)

def pow3(x):
    return x ** 3

def noop(x):
    pass

#
# Test code

```

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

### Starting and Serving Forever with asyncio

Source: https://docs.python.org/3.10/library/asyncio-eventloop.html

Shows how to start an asyncio server and keep it running indefinitely to accept client connections. This example uses a client_connected callback to handle communication.

```python
async def client_connected(reader, writer):
    # Communicate with the client with
    # reader/writer streams.  For example:
    await reader.readline()

async def main(host, port):
    srv = await asyncio.start_server(
        client_connected, host, port)
    await srv.serve_forever()

asyncio.run(main('127.0.0.1', 0))
```

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

### Main Application Setup

Source: https://docs.python.org/3.10/howto/logging-cookbook.html

Sets up the Qt application, creates the main window, and starts the event loop. It also configures the root logger to a DEBUG level.

```python
def main():
    QtCore.QThread.currentThread().setObjectName('MainThread')
    logging.getLogger().setLevel(logging.DEBUG)
    app = QtWidgets.QApplication(sys.argv)
    example = Window(app)
    example.show()
    sys.exit(app.exec_())

if __name__=='__main__':
    main()

```

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

### Basic Distutils Setup Script

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

A fundamental example of a Python setup script using Distutils. It includes essential metadata and specifies packages for distribution.

```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'],
     )

```

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

### tzinfo Examples Setup

Source: https://docs.python.org/3.10/library/datetime.html

This code sets up common timedelta constants and imports necessary classes from the datetime module for creating tzinfo subclasses.

```python
from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)
```

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

### C Extension Module Setup

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

This setup.py example demonstrates how to define and include a C extension module. It specifies compiler definitions, include directories, and source files for the extension.

```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 ] )

```

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

### Process Lifecycle Example

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

Demonstrates starting a process, checking its alive status, terminating it, and verifying the exit code.

```python
import multiprocessing, time, signal
p = multiprocessing.Process(target=time.sleep, args=(1000,))
print(p, p.is_alive())
p.start()
print(p, p.is_alive())
p.terminate()
time.sleep(0.1)
print(p, p.is_alive())
p.exitcode == -signal.SIGTERM
True
```

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

### Basic Readline Completion Setup

Source: https://docs.python.org/3.10/library/rlcompleter.html

This example demonstrates how to set up tab completion for the `readline` module using `rlcompleter`. It automatically binds the tab key to the completion function.

```python
import rlcompleter
import readline
readline.parse_and_bind("tab: complete")
readline. <TAB PRESSED>
```

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

### Manual Event Loop Execution (for comparison)

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

This example shows the manual setup and execution of an asyncio event loop, which asyncio.run() abstracts away. It is generally recommended to use asyncio.run() instead.

```python
import asyncio

async def main():
    await asyncio.sleep(0)
    return 42

loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
try:
    loop.run_until_complete(main())
finally:
    asyncio.set_event_loop(None)
    loop.close()
```

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

### Complete Python Initialization Example

Source: https://docs.python.org/3.10/c-api/init_config.html

A comprehensive example demonstrating how to modify default Python configuration, read configuration, and override specific parameters like program name, module search paths, and executable path.

```c
PyStatus init_python(const char *program_name)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name before reading the configuration
       (decode byte string from the locale encoding).

       Implicitly preinitialize Python. */
    status = PyConfig_SetBytesString(&config, &config.program_name,
                                     program_name);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Read all configuration at once */
    status = PyConfig_Read(&config);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Append our custom search path to sys.path */
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Override executable computed by PyConfig_Read() */
    status = PyConfig_SetString(&config, &config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    status = Py_InitializeFromConfig(&config);

done:
    PyConfig_Clear(&config);
    return status;
}

```

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

### Install Python on OpenBSD

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

Use the pkg_add command to install Python on OpenBSD. This example shows installing a specific version for i386 architecture.

```bash
pkg_add -r python

pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/<insert your architecture here>/python-<version>.tgz

For example i386 users get the 2.5.1 version of Python using:

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

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

### Get Package Version

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

Retrieve the version string of an installed package. Ensure the package is installed in the current environment.

```python
from importlib.metadata import version
version('wheel')
```

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

### Test Case with setUp() for Fixture Setup

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

Demonstrates using the `setUp()` method to create a test fixture before each test method runs. This is useful for initializing common objects or states.

```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')

```

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

### Get Start Attribute from Unicode Exception

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

Retrieves the start attribute from a Unicode exception object. The start attribute must not be NULL. Returns 0 on success, -1 on failure.

```c
int PyUnicodeDecodeError_GetStart(PyObject *_exc_ , Py_ssize_t *_start_)

```

```c
int PyUnicodeEncodeError_GetStart(PyObject *_exc_ , Py_ssize_t *_start_)

```

```c
int PyUnicodeTranslateError_GetStart(PyObject *_exc_ , Py_ssize_t *_start_)

```

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

### distutils.core.run_setup

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

Executes a setup script in a controlled environment, returning the Distribution instance that manages the build process.

```APIDOC
## run_setup(script_name, script_args=None, stop_after='run')

### Description
Run a setup script in a somewhat controlled environment, and return the distutils.dist.Distribution instance that drives things. This is useful if you need to find out the distribution meta-data (passed as keyword args from script to setup()), or the contents of the config files or command-line.

### Method
run_setup

### Parameters
#### Arguments
- **script_name** (string) - A file that will be read and run with exec(). sys.argv[0] will be replaced with script_name for the duration of the call.
- **script_args** (list of strings, optional) - If supplied, sys.argv[1:] will be replaced by script_args for the duration of the call.
- **stop_after** (string, optional) - Tells setup() when to stop processing. Possible values: 'init', 'config', 'commandline', 'run'. Defaults to 'run'.
  - 'init': Stop after the Distribution instance has been created and populated with the keyword arguments to setup()
  - 'config': Stop after config files have been parsed
  - 'commandline': Stop after the command-line arguments have been parsed
  - 'run': Stop after all commands have been run (default)
```

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

### Get All Installation Paths for a Scheme

Source: https://docs.python.org/3.10/library/sysconfig.html

Returns a dictionary containing all installation paths for a specified scheme. Paths can be expanded or left unexpanded.

```python
import sysconfig

all_paths = sysconfig.get_paths(scheme="posix_prefix", expand=True)
print(all_paths)
```

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

### Command-Line Equivalent for Build Configuration

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

Demonstrates the command-line arguments that correspond to the 'build-base=blib' and 'force=1' settings in a setup.cfg file.

```bash
python setup.py build --build-base=blib --force

```

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

### Get Specific Installation Path

Source: https://docs.python.org/3.10/library/sysconfig.html

Retrieves a specific installation path by name from a given scheme. Paths can be expanded using configuration variables.

```python
import sysconfig

stdlib_path = sysconfig.get_path("stdlib", scheme="posix_prefix")
print(stdlib_path)
```

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

### Basic Package Setup

Source: https://docs.python.org/3.10/distutils/examples.html

A minimal setup.py script for a package named 'foobar'. This is used to demonstrate the 'check' command.

```python
from distutils.core import setup

setup(name='foobar')

```

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

### Reading Package Metadata with importlib.metadata

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

Use importlib.metadata to retrieve version, requirements, and files for installed packages. This example requires the 'requests' package to be installed.

```python
from importlib.metadata import version, requires, files
version('requests')
list(requires('requests'))
list(files('requests'))[:5]
```

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

### Basic Sub-command Setup with argparse

Source: https://docs.python.org/3.10/library/argparse.html

Demonstrates creating a main parser with subparsers for 'a' and 'b' commands, each with their own arguments. Shows how to parse arguments for these sub-commands.

```python
# create the top-level parser
parser = argparse.ArgumentParser(prog='PROG')
parser.add_argument('--foo', action='store_true', help='foo help')
subparsers = parser.add_subparsers(help='sub-command help')

# create the parser for the "a" command
parser_a = subparsers.add_parser('a', help='a help')
parser_a.add_argument('bar', type=int, help='bar help')

# create the parser for the "b" command
parser_b = subparsers.add_parser('b', help='b help')
parser_b.add_argument('--baz', choices='XYZ', help='baz help')

# parse some argument lists
parser.parse_args(['a', '12'])
parser.parse_args(['--foo', 'b', '--baz', 'Z'])
```

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

### GET Request Example

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

Demonstrates how to make a GET request and read the response status, reason, and body. It also shows how to read the response in chunks.

```APIDOC
## GET /

### Description
Retrieves a resource from the server.

### Method
GET

### Endpoint
/

### Request Example
```python
import http.client
conn = http.client.HTTPSConnection("www.python.org")
conn.request("GET", "/")
r1 = conn.getresponse()
print(r1.status, r1.reason)
data1 = r1.read()
```

### Response
#### Success Response (200)
- **status** (int) - The HTTP status code.
- **reason** (string) - The reason phrase for the status code.
- **body** (bytes) - The response body.

#### Response Example
```
200 OK
<!doctype html>
<!--[if"...
```

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

### Setup with Ext Package Argument

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

Configures multiple extensions to reside within a specified package using the 'ext_package' argument in setup().

```python
setup(...,
      ext_package='pkg',
      ext_modules=[Extension('foo', ['foo.c']),
                   Extension('subpkg.bar', ['bar.c'])],
     )
```

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

### Get Hexdigest of SHA-224 Hash

Source: https://docs.python.org/3.10/library/hashlib.html

A more condensed example showing how to directly create a SHA-224 hash object with data and immediately get its hexadecimal digest.

```python
hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
```

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

### setup_scripts

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

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

```APIDOC
## setup_scripts

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

### Method
Not specified (internal method)

### Parameters
* `_context_`: Context object for the operation.
```

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

### Getting Start and End Indices of a Match

Source: https://docs.python.org/3.10/library/re.html

Demonstrates the start() and end() methods for retrieving the start and end indices of a matched substring. These methods default to group 0 (the entire match) but can be used for specific subgroups.

```python
m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
# Example usage: m.string[m.start(g):m.end(g)]
```

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

### Add Module with Additional Libraries to Setup File

Source: https://docs.python.org/3.10/extending/extending.html

Include this line in `Modules/Setup.local` if your module requires external libraries for linking.

```makefile
spam spammodule.o -lX11

```

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

### Verify Tix Installation

Source: https://docs.python.org/3.10/library/tkinter.tix.html

This snippet checks if the Tix package is installed and accessible by the Tk interpreter. It's a useful test for confirming a correct Tix setup.

```python
from tkinter import tix
root = tix.Tk()
root.tk.eval('package require Tix')
```

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

### Example HTML Parser Application

Source: https://docs.python.org/3.10/library/html.parser.html

This example demonstrates how to subclass HTMLParser to create a simple parser that prints encountered start tags, end tags, and data.

```python
from html.parser import HTMLParser

class MyHTMLParser(HTMLParser):
    def handle_starttag(self, tag, attrs):
        print("Encountered a start tag:", tag)

    def handle_endtag(self, tag):
        print("Encountered an end tag :", tag)

    def handle_data(self, data):
        print("Encountered some data  :", data)

parser = MyHTMLParser()
parser.feed('<html><head><title>Test</title></head>'
            '<body><h1>Parse me!</h1></body></html>')
```

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

### Logging Configuration Server Example

Source: https://docs.python.org/3.10/howto/logging-cookbook.html

Sets up a logging configuration server to listen for updates on a specified port. It then logs messages at different levels in a loop until interrupted.

```python
import logging
import logging.config
import time
import os

# read initial config file
logging.config.fileConfig('logging.conf')

# create and start listener on port 9999
t = logging.config.listen(9999)
t.start()

logger = logging.getLogger('simpleExample')

try:
    # loop through logging calls to see the difference
    # new configurations make, until Ctrl+C is pressed
    while True:
        logger.debug('debug message')
        logger.info('info message')
        logger.warning('warn message')
        logger.error('error message')
        logger.critical('critical message')
        time.sleep(5)
except KeyboardInterrupt:
    # cleanup
    logging.config.stopListening()
    t.join()

```

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

### Mark String for Translation

Source: https://docs.python.org/3.10/library/gettext.html

Example of marking a string for translation using the installed '_' function.

```python
print(_('This string will be translated.'))
```

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

### Basic setup.py for a C Extension

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

This is a minimal setup.py file to compile a single C source file into a Python extension module. It defines the extension name and its source file.

```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])

```

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

### Unattended Python Installation Configuration

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

This XML file specifies installation options and values for an unattended installation, mirroring the settings of the previous command-line example. Values provided as attributes are converted to numbers if possible, while element text values remain strings.

```xml
<Options>
    <Option Name="InstallAllUsers" Value="no" />
    <Option Name="Include_launcher" Value="0" />
    <Option Name="Include_test" Value="no" />
    <Option Name="SimpleInstall" Value="yes" />
    <Option Name="SimpleInstallDescription">Just for me, no test suite</Option>
</Options>

```

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

### Configuring 'build_ext' inplace Option in setup.cfg

Source: https://docs.python.org/3.10/distutils/configfile.html

This example shows how to set the `inplace=1` option for the `build_ext` command in `setup.cfg`. This ensures extensions are built in the source directory without needing to specify the option on the command line.

```ini
[build_ext]
inplace=1
```

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

### Getting Context with `get_context`

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

Illustrates using `get_context` to obtain a context object for a specific start method ('spawn' in this case). This allows for multiple start methods within the same program and is preferred for libraries.

```python
import multiprocessing as mp

def foo(q):
    q.put('hello')

if __name__ == '__main__':
    ctx = mp.get_context('spawn')
    q = ctx.Queue()
    p = ctx.Process(target=foo, args=(q,))
    p.start()
    print(q.get())
    p.join()

```

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

### Get Supported Scheme Names

Source: https://docs.python.org/3.10/library/sysconfig.html

Retrieves a tuple of all currently supported installation scheme names in sysconfig.

```python
import sysconfig

schemes = sysconfig.get_scheme_names()
print(schemes)
```

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

### Distutils setup.py with Classifiers

Source: https://docs.python.org/3.10/whatsnew/2.3.html

An example of a `setup.py` file demonstrating the use of the `classifiers` keyword argument for Distutils package metadata.

```python
from distutils import core
kw = {"name": "Quixote",
      "version": "0.5.1",
      "description": "A highly Pythonic Web application framework",
      # ...
      }

if (hasattr(core, 'setup_keywords') and
    'classifiers' in core.setup_keywords):
    kw['classifiers'] = \
        ['Topic :: Internet :: WWW/HTTP :: Dynamic Content',
         'Environment :: No Input/Output (Daemon)',
         'Intended Audience :: Developers'],

core.setup(**kw)
```

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

### Getting All Global Site-Packages Directories

Source: https://docs.python.org/3.10/library/site.html

Retrieves a list of all global site-packages directories configured for the Python installation.

```python
import site
print(site.getsitepackages())

```

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

### modules_setup

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

Returns a copy of sys.modules.

```APIDOC
## modules_setup

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

### Method
N/A (Function)
```

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

### Example command-line for 'extend' action

Source: https://docs.python.org/3.10/library/optparse.html

Demonstrates how multiple '--names' options with comma-delimited values are processed by the 'extend' action.

```text
--names=foo,bar --names blah --names ding,dong
```

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

### Module Name Example

Source: https://docs.python.org/3.10/glossary.html

Shows how to get the fully qualified name of a module using the `__name__` attribute.

```python
import email.mime.text
>>> email.mime.text.__name__ 
'email.mime.text'

```

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

### tracemalloc.get_traceback_limit

Source: https://docs.python.org/3.10/library/tracemalloc.html

Gets the maximum number of frames stored in the traceback of a trace. The limit is set by the start() function.

```APIDOC
## tracemalloc.get_traceback_limit

### Description
Get the maximum number of frames stored in the traceback of a trace. The `tracemalloc` module must be tracing memory allocations to get the limit, otherwise an exception is raised. The limit is set by the `start()` function.

### Returns
- **int**: The maximum number of frames stored in the traceback.

```

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

### SSL Server Context Example

Source: https://docs.python.org/3.10/library/ssl.html

Illustrates setting up an SSL server context, loading a certificate chain and private key, and binding a socket to listen for incoming secure connections. This example listens on localhost IPv4.

```python
import ssl
import socket

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.load_cert_chain('/path/to/certchain.pem', '/path/to/private.key')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    sock.bind(('127.0.0.1', 8443))
    sock.listen(5)
    with context.wrap_socket(sock, server_side=True) as ssock:
        conn, addr = ssock.accept()
        ...
```

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

### Python Interpreter Information

Source: https://docs.python.org/3.10/faq/windows.html

Example output when starting the Python interpreter, showing version and system details.

```text
Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit (Intel)] on win32\nType \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n>>>\n
```

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

### post_setup

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

A placeholder method that can be overridden to pre-install packages or perform other post-creation steps in the virtual environment.

```APIDOC
## post_setup

### Description
A placeholder method which can be overridden in third party implementations to pre-install packages in the virtual environment or perform other post-creation steps.

### Method
Not specified (internal method)

### Parameters
* `_context_`: Context object for the operation.

### Changed in version
3.7.2: Windows now uses redirector scripts for `python[w].exe` instead of copying the actual binaries. In 3.7.2 only `setup_python()` does nothing unless running from a build in the source tree.
3.7.3: Windows copies the redirector scripts as part of `setup_python()` instead of `setup_scripts()`. This was not the case in 3.7.2. When using symlinks, the original executables will be linked.
```

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

### distutils.core.setup

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

The main function to initiate the package building process. It accepts numerous arguments to configure package metadata, files, and build options.

```APIDOC
## setup()

### Description
The basic do-everything function that does most everything you could ever ask for from a Distutils method.

### Method
setup

### Parameters
#### Arguments
- **name** (string) - The name of the package
- **version** (string) - The version number of the package
- **description** (string) - A single line describing the package
- **long_description** (string) - Longer description of the package
- **author** (string) - The name of the package author
- **author_email** (string) - The email address of the package author
- **maintainer** (string) - The name of the current maintainer, if different from the author
- **maintainer_email** (string) - The email address of the current maintainer
- **url** (string) - A URL for the package (homepage)
- **download_url** (string) - A URL to download the package
- **packages** (list of strings) - A list of Python packages that distutils will manipulate
- **py_modules** (list of strings) - A list of Python modules that distutils will manipulate
- **scripts** (list of strings) - A list of standalone script files to be built and installed
- **ext_modules** (list of distutils.core.Extension) - A list of Python extensions to be built
- **classifiers** (list of strings) - A list of categories for the package
- **distclass** (subclass of distutils.core.Distribution) - the Distribution class to use
- **script_name** (string) - The name of the setup.py script
- **script_args** (list of strings) - Arguments to supply to the setup script
- **options** (dictionary) - default options for the setup script
- **license** (string) - The license for the package
- **keywords** (list of strings or comma-separated string) - Descriptive meta-data
- **platforms** (list of strings or comma-separated string) - Platforms supported by the package
- **cmdclass** (dictionary) - A mapping of command names to Command subclasses
- **data_files** (list) - A list of data files to install
- **package_dir** (dictionary) - A mapping of package to directory names
```

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

### Get Supported Path Names

Source: https://docs.python.org/3.10/library/sysconfig.html

Retrieves a tuple of all currently supported installation path names within sysconfig.

```python
import sysconfig

path_names = sysconfig.get_path_names()
print(path_names)
```

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

### Get Help for Screen bgcolor Method

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

Displays the docstring for the Screen.bgcolor method, showing its signature and usage examples.

```python
help(Screen.bgcolor)
```

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

### Basic Setup Script

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

A minimal setup script for a Python module named 'foo'. It specifies the module name, version, and the Python modules included.

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

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

### Adding a Library to Setup File

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

Appends a library, such as '-lm' for the math library, to an existing module definition in the Setup file.

```text
foo foomodule.c -lm

```

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

### Initialize Python with Multi-Phase Initialization

Source: https://docs.python.org/3.10/c-api/init_config.html

Demonstrates how to initialize Python in multiple phases, allowing custom code execution between the 'Core' and 'Main' initialization stages. Use sys.stderr for output before sys.stdout is available.

```c
void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config._init_main = 0;

    /* ... customize 'config' configuration ... */

    status = Py_InitializeFromConfig(&config);
    PyConfig_Clear(&config);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }

    /* Use sys.stderr because sys.stdout is only created
       by _Py_InitializeMain() */
    int res = PyRun_SimpleString(
        "import sys; "
        "print('Run Python code before _Py_InitializeMain', "
               "file=sys.stderr)");
    if (res < 0) {
        exit(1);
    }

    /* ... put more configuration code here ... */

    status = _Py_InitializeMain();
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
}

```

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

### Find Line Start Offsets in Code

Source: https://docs.python.org/3.10/library/dis.html

Use `findlinestarts` to get pairs of (offset, lineno) indicating the start of each source code line within a code object. It utilizes the `co_lines` method for accurate line mapping.

```python
import dis

def multi_line_func():
    a = 1
    b = 2
    return a + b

for offset, lineno in dis.findlinestarts(multi_line_func.__code__):
    print(f'Offset: {offset}, Line: {lineno}')
```

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

### Get Distribution Metadata

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

Retrieve a list of metadata keys for an installed distribution. This provides information such as Name, Version, and Summary.

```python
from importlib.metadata import metadata
list(metadata('wheel'))
```

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

### Connect Existing Socket Example

Source: https://docs.python.org/3.10/library/asyncio-protocol.html

Shows how to wait for data on an existing socket using `loop.create_connection()`. The example simulates data reception by writing to a paired socket.

```Python
import asyncio
import socket


class MyProtocol(asyncio.Protocol):

    def __init__(self, on_con_lost):
        self.transport = None
        self.on_con_lost = on_con_lost

    def connection_made(self, transport):
        self.transport = transport

    def data_received(self, data):
        print("Received:", data.decode())

        # We are done: close the transport;
        # connection_lost() will be called automatically.
        self.transport.close()

    def connection_lost(self, exc):
        # The socket has been closed
        self.on_con_lost.set_result(True)


async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()
    on_con_lost = loop.create_future()

    # Create a pair of connected sockets
    rsock, wsock = socket.socketpair()

    # Register the socket to wait for data.
    transport, protocol = await loop.create_connection(
        lambda: MyProtocol(on_con_lost), sock=rsock)

    # Simulate the reception of data from the network.
    loop.call_soon(wsock.send, 'abc'.encode())

    try:
        await protocol.on_con_lost
    finally:
        transport.close()
        wsock.close()

asyncio.run(main())

```

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

### Get Unicode Bidirectional Property

Source: https://docs.python.org/3.10/library/unicodedata.html

Retrieves the bidirectional property of a Unicode character. For example, 'AN' indicates an Arabic number.

```python
import unicodedata

unicodedata.bidirectional('
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																	
```

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

### Get Unicode Character Category

Source: https://docs.python.org/3.10/library/unicodedata.html

Retrieves the general category of a Unicode character. For example, 'Lu' indicates an uppercase letter.

```python
import unicodedata

unicodedata.category('A')  # 'L'etter, 'u'ppercase
```

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

### Basic FTP Session Example

Source: https://docs.python.org/3.10/library/ftplib.html

Demonstrates a typical FTP session including connecting, logging in, changing directories, listing contents, retrieving files, and quitting.

```python
from ftplib import FTP
ftp = FTP('ftp.us.debian.org')  # connect to host, default port
ftp.login()                     # user anonymous, passwd anonymous@
'230 Login successful.'
ftp.cwd('debian')               # change into "debian" directory
'250 Directory successfully changed.'
ftp.retrlines('LIST')           # list directory contents
-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
...
drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
'226 Directory send OK.'
with open('README', 'wb') as fp:
    ftp.retrbinary('RETR README', fp.write)
'226 Transfer complete.'
ftp.quit()
'221 Goodbye.'
```

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

### Certificate Chain Example

Source: https://docs.python.org/3.10/library/ssl.html

A sequence of certificates concatenated together, starting with the server certificate and ending with a self-signed root certificate.

```text
-----BEGIN CERTIFICATE-----
... (certificate for your server)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the certificate for the CA)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the root certificate for the CA's issuer)...
-----END CERTIFICATE-----
```

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

### Building the Extension Module

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

Command to compile the C source file and create the extension module using the setup.py script.

```bash
python setup.py build

```

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

### Get Default Scheme Name

Source: https://docs.python.org/3.10/library/sysconfig.html

Returns the default installation scheme name for the current platform. This function was previously an implementation detail.

```python
import sysconfig

default_scheme = sysconfig.get_default_scheme()
print(default_scheme)
```

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

### Get Distribution IDs from Freedesktop OS Release

Source: https://docs.python.org/3.10/library/platform.html

Example function to extract distribution ID and ID_LIKE fields from the freedesktop_os_release() output.

```python
def get_like_distro():
    info = platform.freedesktop_os_release()
    ids = [info["ID"]]
    if "ID_LIKE" in info:
        # ids are space separated and ordered by precedence
        ids.extend(info["ID_LIKE"].split())
    return ids
```

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

### Install Python using make altinstall

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

Use 'make altinstall' instead of 'make install' to avoid overwriting the 'python3' binary and ensure version-specific installation.

```bash
make altinstall
```

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

### tracemalloc.start

Source: https://docs.python.org/3.10/library/tracemalloc.html

Starts tracing Python memory allocations, installing hooks on memory allocators. The number of traceback frames collected can be specified.

```APIDOC
## tracemalloc.start

### Description
Start tracing Python memory allocations: install hooks on Python memory allocators. Collected tracebacks of traces will be limited to _nframe_ frames. By default, a trace of a memory block only stores the most recent frame: the limit is `1`. _nframe_ must be greater or equal to `1`.

### Parameters
#### Path Parameters
- **_nframe_** (int) - Optional. The maximum number of frames to store in the traceback. Defaults to 1.

### See Also
stop(), is_tracing(), get_traceback_limit()

### Notes
Storing more than `1` frame increases memory and CPU overhead. The `PYTHONTRACEMALLOC` environment variable or the `-X tracemalloc=NFRAME` command line option can be used to start tracing at startup.

```

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

### Define command-line options with optparse

Source: https://docs.python.org/3.10/whatsnew/2.3.html

Illustrates how to set up an OptionParser to define command-line arguments, including their type and help messages.

```python
import sys
from optparse import OptionParser

op = OptionParser()
op.add_option('-i', '--input',
              action='store', type='string', dest='input',
              help='set input filename')
op.add_option('-l', '--length',
              action='store', type='int', dest='length',
              help='set maximum length of output')
```

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

### Python count iterator example

Source: https://docs.python.org/3.10/library/itertools.html

Generates an iterator of evenly spaced values starting from a specified number. Can be used with map() or zip().

```Python
def count(start=0, step=1):
    # count(10) --> 10 11 12 13 14 ...
    # count(2.5, 0.5) -> 2.5 3.0 3.5 ...
    n = start
    while True:
        yield n
        n += step

```

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

### Test Case with setUp() and tearDown() for Fixture Management

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

Illustrates using both `setUp()` for setup and `tearDown()` for cleanup after each test method. `tearDown()` is guaranteed to run if `setUp()` succeeds.

```python
import unittest

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

    def tearDown(self):
        self.widget.dispose()

```

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

### Start an HTTP server for documentation

Source: https://docs.python.org/3.10/library/pydoc.html

Start an HTTP server on a specified port to browse documentation via a web browser. Port 0 selects an arbitrary unused port.

```shell
python -m pydoc -p 1234
```
Tokens:
Raw