pythonlings 0.3.0__py3-none-any.whl

pythonlings/docs/topics/conditionals.md

@@ -0,0 +1,88 @@
+# Conditionals
+
+Source: https://docs.python.org/3/tutorial/controlflow.html#if-statements
+
+This local reference is generated from the official Python documentation and trimmed for pythonlings.
+
+`if`, `elif`, and `else` choose which block runs based on boolean conditions.
+
+## Extracted reference
+
+4.1. `if` Statements
+
+Perhaps the most well-known statement type is the `if` statement. For
+example:
+
+```python
+>>> x = int(input("Please enter an integer: "))
+Please enter an integer: 42
+>>> if x < 0:
+... x = 0
+... print('Negative changed to zero')
+... elif x == 0:
+... print('Zero')
+... elif x == 1:
+... print('Single')
+... else:
+... print('More')
+...
+More
+
+```
+
+There can be zero or more `elif` parts, and the `else` part is
+optional. The keyword ‘`elif`’ is short for ‘else if’, and is useful
+to avoid excessive indentation. An `if` … `elif` …
+`elif` … sequence is a substitute for the `switch` or
+`case` statements found in other languages.
+
+If you’re comparing the same value to several constants, or checking for specific types or
+attributes, you may also find the `match` statement useful. For more
+details see match Statements.
+
+## More reference
+
+Source: https://docs.python.org/3/tutorial/controlflow.html#match-statements
+
+`match` pattern matching with examples and syntax.
+
+4.7. `match` Statements
+
+A `match` statement takes an expression and compares its value to successive
+patterns given as one or more case blocks. This is superficially
+similar to a switch statement in C, Java or JavaScript (and many
+other languages), but it’s more similar to pattern matching in
+languages like Rust or Haskell. Only the first pattern that matches
+gets executed and it can also extract components (sequence elements
+or object attributes) from the value into variables. If no case matches,
+none of the branches is executed.
+
+The simplest form compares a subject value against one or more literals:
+
+```python
+def http_error(status):
+match status:
+case 400:
+return "Bad request"
+case 404:
+return "Not found"
+case 418:
+return "I'm a teapot"
+case _:
+return "Something's wrong with the internet"
+
+```
+
+Note the last block: the “variable name” `_` acts as a wildcard and
+never fails to match.
+
+You can combine several literals in a single pattern using `|` (“or”):
+
+```python
+case 401 | 403 | 404:
+return "Not allowed"
+
+```
+
+Patterns can look like unpacking assignments, and can be used to bind
+variables:

pythonlings/docs/topics/context_managers.md

@@ -0,0 +1,97 @@
+# Context Managers
+
+Source: https://docs.python.org/3/reference/compound_stmts.html#the-with-statement
+
+This local reference is generated from the official Python documentation and trimmed for pythonlings.
+
+Context managers run setup and cleanup around a block using `with`.
+
+## Extracted reference
+
+8.5. The `with` statement
+
+The `with` statement is used to wrap the execution of a block with
+methods defined by a context manager (see section With Statement Context Managers).
+This allows common `try`…`except`…`finally`
+usage patterns to be encapsulated for convenient reuse.
+
+```python
+
+with_stmt: "with" ( "(" with_stmt_contents ","? ")" | with_stmt_contents ) ":" suite
+with_stmt_contents: with_item ("," with_item)*
+with_item: expression ["as" target]
+
+```
+
+The execution of the `with` statement with one “item” proceeds as follows:
+
+-
+
+The context expression (the expression given in the
+`with_item`) is evaluated to obtain a context manager.
+
+-
+
+The context manager’s `__enter__()` is loaded for later use.
+
+-
+
+The context manager’s `__exit__()` is loaded for later use.
+
+-
+
+The context manager’s `__enter__()` method is invoked.
+
+-
+
+If a target was included in the `with` statement, the return value
+from `__enter__()` is assigned to it.
+
+Note
+
+## More reference
+
+Source: https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager
+
+`contextlib.contextmanager` builds a context manager from a generator.
+
+@contextlib.contextmanager
+
+This function is a decorator that can be used to define a factory
+function for `with` statement context managers, without needing to
+create a class or separate `__enter__()` and `__exit__()` methods.
+
+While many objects natively support use in with statements, sometimes a
+resource needs to be managed that isn’t a context manager in its own right,
+and doesn’t implement a `close()` method for use with `contextlib.closing`.
+
+An abstract example would be the following to ensure correct resource
+management:
+
+```python
+from contextlib import contextmanager
+
+@contextmanager
+def managed_resource(*args, **kwds):
+# Code to acquire resource, e.g.:
+resource = acquire_resource(*args, **kwds)
+try:
+yield resource
+finally:
+# Code to release resource, e.g.:
+release_resource(resource)
+
+```
+
+The function can then be used like this:
+
+```python
+>>> with managed_resource(timeout=3600) as resource:
+... # Resource is released at the end of this block,
+... # even if code in the block raises an exception
+
+```
+
+The function being decorated must return a generator-iterator when
+called. This iterator must yield exactly one value, which will be bound to
+the targets in the `with` statement’s `as` clause, if any.

pythonlings/docs/topics/dataclasses.md

@@ -0,0 +1,97 @@
+# Dataclasses
+
+Source: https://docs.python.org/3/library/dataclasses.html
+
+This local reference is generated from the official Python documentation and trimmed for pythonlings.
+
+Dataclasses generate common class methods for data-focused classes.
+
+## Extracted reference
+
+dataclasses — Data Classes — Python 3.14.6 documentation
+
+Navigation
+
+-
+index
+
+-
+modules |
+
+-
+next |
+
+-
+previous |
+
+-
+
+- Python »
+
+-
+
+-
+
+-
+3.14.6 Documentation »
+
+- The Python Standard Library »
+
+- Python Runtime Services »
+
+- `dataclasses` — Data Classes
+
+-
+
+|
+
+-
+
+Theme
+
+## More reference
+
+Source: https://docs.python.org/3/tutorial/classes.html#class-and-instance-variables
+
+Class vs instance variables — the distinction behind dataclass fields.
+
+9.3.5. Class and Instance Variables
+
+Generally speaking, instance variables are for data unique to each instance
+and class variables are for attributes and methods shared by all instances
+of the class:
+
+```python
+class Dog:
+
+kind = 'canine' # class variable shared by all instances
+
+def __init__(self, name):
+self.name = name # instance variable unique to each instance
+
+>>> d = Dog('Fido')
+>>> e = Dog('Buddy')
+>>> d.kind # shared by all dogs
+'canine'
+>>> e.kind # shared by all dogs
+'canine'
+>>> d.name # unique to d
+'Fido'
+>>> e.name # unique to e
+'Buddy'
+
+```
+
+As discussed in A Word About Names and Objects, shared data can have possibly surprising
+effects involving mutable objects such as lists and dictionaries.
+For example, the tricks list in the following code should not be used as a
+class variable because just a single list would be shared by all Dog
+instances:
+
+```python
+class Dog:
+
+tricks = [] # mistaken use of a class variable
+
+def __init__(self, name):
+self.name = name

pythonlings/docs/topics/datetime.md

@@ -0,0 +1,97 @@
+# Datetime
+
+Source: https://docs.python.org/3/library/datetime.html
+
+This local reference is generated from the official Python documentation and trimmed for pythonlings.
+
+`datetime` represents dates, times, durations, and time zones.
+
+## Extracted reference
+
+datetime — Basic date and time types — Python 3.14.6 documentation
+
+Navigation
+
+-
+index
+
+-
+modules |
+
+-
+next |
+
+-
+previous |
+
+-
+
+- Python »
+
+-
+
+-
+
+-
+3.14.6 Documentation »
+
+- The Python Standard Library »
+
+- Data Types »
+
+- `datetime` — Basic date and time types
+
+-
+
+|
+
+-
+
+Theme
+
+## More reference
+
+Source: https://docs.python.org/3/library/datetime.html#examples-of-usage-datetime
+
+Worked `datetime` examples beyond the API reference.
+
+Examples of usage: `datetime`
+
+Examples of working with `datetime` objects:
+
+```python
+>>> import datetime as dt
+
+>>> # Using datetime.combine()
+>>> d = dt.date(2005, 7, 14)
+>>> t = dt.time(12, 30)
+>>> dt.datetime.combine(d, t)
+datetime.datetime(2005, 7, 14, 12, 30)
+
+>>> # Using datetime.now()
+>>> dt.datetime.now()
+datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1
+>>> dt.datetime.now(dt.timezone.utc)
+datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)
+
+>>> # Using datetime.strptime()
+>>> my_datetime = dt.datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
+>>> my_datetime
+datetime.datetime(2006, 11, 21, 16, 30)
+
+>>> # Using datetime.timetuple() to get tuple of all attributes
+>>> tt = my_datetime.timetuple()
+>>> for it in tt:
+... print(it)
+...
+2006 # year
+11 # month
+21 # day
+16 # hour
+30 # minute
+0 # second
+1 # weekday (0 = Monday)
+325 # number of days since 1st January
+-1 # dst - method tzinfo.dst() returned None
+
+>>> # Date in ISO format

pythonlings/docs/topics/decorators.md

@@ -0,0 +1,91 @@
+# Decorators
+
+Source: https://docs.python.org/3/reference/compound_stmts.html#function-definitions
+
+This local reference is generated from the official Python documentation and trimmed for pythonlings.
+
+Decorators wrap or transform functions and classes with `@decorator` syntax.
+
+## Extracted reference
+
+8.7. Function definitions
+
+A function definition defines a user-defined function object (see section
+The standard type hierarchy):
+
+```python
+
+funcdef: [decorators] "def" funcname [type_params] "(" [parameter_list] ")"
+["->" expression] ":" suite
+decorators: decorator+
+decorator: "@" assignment_expression NEWLINE
+parameter_list: defparameter ("," defparameter)* "," "/" ["," [parameter_list_no_posonly]]
+| parameter_list_no_posonly
+parameter_list_no_posonly: defparameter ("," defparameter)* ["," [parameter_list_starargs]]
+| parameter_list_starargs
+parameter_list_starargs: "*" [star_parameter] ("," defparameter)* ["," [parameter_star_kwargs]]
+| "*" ("," defparameter)+ ["," [parameter_star_kwargs]]
+| parameter_star_kwargs
+parameter_star_kwargs: "**" parameter [","]
+parameter: identifier [":" expression]
+star_parameter: identifier [":" ["*"] expression]
+defparameter: parameter ["=" expression]
+funcname: identifier
+
+```
+
+A function definition is an executable statement. Its execution binds the
+function name in the current local namespace to a function object (a wrapper
+around the executable code for the function). This function object contains a
+reference to the current global namespace as the global namespace to be used
+when the function is called.
+
+The function definition does not execute the function body; this gets executed
+only when the function is called. [4]
+
+A function definition may be wrapped by one or more decorator expressions.
+Decorator expressions are evaluated when the function is defined, in the scope
+that contains the function definition. The result must be a callable, which is
+invoked with the function object as the only argument. The returned value is
+bound to the function name instead of the function object. Multiple decorators
+
+## More reference
+
+Source: https://docs.python.org/3/library/functools.html#functools.wraps
+
+`functools.wraps` preserves the wrapped function's metadata.
+
+@functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
+
+This is a convenience function for invoking `update_wrapper()` as a
+function decorator when defining a wrapper function. It is equivalent to
+`partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)`.
+For example:
+
+```python
+>>> from functools import wraps
+>>> def my_decorator(f):
+... @wraps(f)
+... def wrapper(*args, **kwds):
+... print('Calling decorated function')
+... return f(*args, **kwds)
+... return wrapper
+...
+>>> @my_decorator
+... def example():
+... """Docstring"""
+... print('Called example function')
+...
+>>> example()
+Calling decorated function
+Called example function
+>>> example.__name__
+'example'
+>>> example.__doc__
+'Docstring'
+
+```
+
+Without the use of this decorator factory, the name of the example function
+would have been `'wrapper'`, and the docstring of the original `example()`
+would have been lost.

pythonlings/docs/topics/dictionaries.md

@@ -0,0 +1,96 @@
+# Dictionaries
+
+Source: https://docs.python.org/3/tutorial/datastructures.html#dictionaries
+
+This local reference is generated from the official Python documentation and trimmed for pythonlings.
+
+Dictionaries map keys to values and are the standard way to represent lookup tables.
+
+## Extracted reference
+
+5.5. Dictionaries
+
+Another useful data type built into Python is the dictionary (see
+Mapping Types — dict). Dictionaries are sometimes found in other languages as
+“associative memories” or “associative arrays”. Unlike sequences, which are
+indexed by a range of numbers, dictionaries are indexed by keys, which can be
+any immutable type; strings and numbers can always be keys. Tuples can be used
+as keys if they contain only strings, numbers, or tuples; if a tuple contains
+any mutable object either directly or indirectly, it cannot be used as a key.
+You can’t use lists as keys, since lists can be modified in place using index
+assignments, slice assignments, or methods like `append()` and
+`extend()`.
+
+It is best to think of a dictionary as a set of key: value pairs,
+with the requirement that the keys are unique (within one dictionary). A pair of
+braces creates an empty dictionary: `{}`. Placing a comma-separated list of
+key:value pairs within the braces adds initial key:value pairs to the
+dictionary; this is also the way dictionaries are written on output.
+
+The main operations on a dictionary are storing a value with some key and
+extracting the value given the key. It is also possible to delete a key:value
+pair with `del`. If you store using a key that is already in use, the old
+value associated with that key is forgotten.
+
+Extracting a value for a non-existent key by subscripting (`d[key]`) raises a
+`KeyError`. To avoid getting this error when trying to access a possibly
+non-existent key, use the `get()` method instead, which returns
+`None` (or a specified default value) if the key is not in the dictionary.
+
+Performing `list(d)` on a dictionary returns a list of all the keys
+used in the dictionary, in insertion order (if you want it sorted, just use
+`sorted(d)` instead). To check whether a single key is in the
+dictionary, use the `in` keyword.
+
+Here is a small example using a dictionary:
+
+```python
+>>> tel = {'jack': 4098, 'sape': 4139}
+>>> tel['guido'] = 4127
+>>> tel
+
+## More reference
+
+Source: https://docs.python.org/3/library/stdtypes.html#mapping-types-dict
+
+The dict type with constructor forms, methods, and creation examples.
+
+Mapping Types — `dict`
+
+A mapping object maps hashable values to arbitrary objects.
+Mappings are mutable objects. There is currently only one standard mapping
+type, the dictionary. (For other containers see the built-in
+`list`, `set`, and `tuple` classes, and the
+`collections` module.)
+
+A dictionary’s keys are almost arbitrary values. Values that are not
+hashable, that is, values containing lists, dictionaries or other
+mutable types (that are compared by value rather than by object identity) may
+not be used as keys.
+Values that compare equal (such as `1`, `1.0`, and `True`)
+can be used interchangeably to index the same dictionary entry.
+
+class dict(**kwargs)
+
+class dict(mapping, /, **kwargs)
+
+class dict(iterable, /, **kwargs)
+
+Return a new dictionary initialized from an optional positional argument
+and a possibly empty set of keyword arguments.
+
+Dictionaries can be created by several means:
+
+-
+
+Use a comma-separated list of `key: value` pairs within braces:
+`{'jack': 4098, 'sjoerd': 4127}` or `{4098: 'jack', 4127: 'sjoerd'}`
+
+-
+
+Use a dict comprehension: `{}`, `{x: x ** 2 for x in range(10)}`
+
+-
+
+Use the type constructor: `dict()`,
+`dict([('foo', 100), ('bar', 200)])`, `dict(foo=100, bar=200)`

pythonlings/docs/topics/enums.md

@@ -0,0 +1,96 @@
+# Enums
+
+Source: https://docs.python.org/3/library/enum.html
+
+This local reference is generated from the official Python documentation and trimmed for pythonlings.
+
+Enums define named constant values that are easier to read than raw literals.
+
+## Extracted reference
+
+enum — Support for enumerations — Python 3.14.6 documentation
+
+Navigation
+
+-
+index
+
+-
+modules |
+
+-
+next |
+
+-
+previous |
+
+-
+
+- Python »
+
+-
+
+-
+
+-
+3.14.6 Documentation »
+
+- The Python Standard Library »
+
+- Data Types »
+
+- `enum` — Support for enumerations
+
+-
+
+|
+
+-
+
+Theme
+
+## More reference
+
+Source: https://docs.python.org/3/library/enum.html#enum.Flag
+
+`Flag` enums combine members with bitwise operators.
+
+class enum.Flag
+
+`Flag` is the same as `Enum`, but its members support the bitwise
+operators `&` (AND), `|` (OR), `^` (XOR), and `~` (INVERT);
+the results of those operations are (aliases of) members of the enumeration.
+
+__contains__(self, value)
+
+Returns True if value is in self:
+
+```python
+>>> from enum import Flag, auto
+>>> class Color(Flag):
+... RED = auto()
+... GREEN = auto()
+... BLUE = auto()
+...
+>>> purple = Color.RED | Color.BLUE
+>>> white = Color.RED | Color.GREEN | Color.BLUE
+>>> Color.GREEN in purple
+False
+>>> Color.GREEN in white
+True
+>>> purple in white
+True
+>>> white in purple
+False
+
+```
+
+__iter__(self)
+
+Returns all contained non-alias members:
+
+```python
+>>> list(Color.RED)
+[<Color.RED: 1>]
+>>> list(purple)
+[<Color.RED: 1>, <Color.BLUE: 4>]