pype_schema.scripts package

Submodules

pype_schema.scripts.generate_allowlist module

Regenerate the allow-lists in operations.py and write allowlist_report.md. Pass --check to change nothing (for CI). The rules, the environment, and the exit codes are described under Custom Mode in docs/advanced.rst.

class pype_schema.scripts.generate_allowlist.Deprecated

Bases: object

Marks a library member that warns or fails when it is read.

pype_schema.scripts.generate_allowlist.attribute_universe(tree)

The objects whose attributes a custom operation may touch.

Parameters:

tree (dict) – Allowed members per namespace; members that are excluded are skipped

Returns:

(label, class or instance) for each object

Return type:

list of tuple

pype_schema.scripts.generate_allowlist.block_versions(block)

The environment recorded in a generated block’s header.

Parameters:

block (str) – The generated block

Returns:

The versions string, or None if the header has none

Return type:

str or None

pype_schema.scripts.generate_allowlist.build_attributes(tree)

Decide which attribute names are allowed on ordinary objects.

Parameters:

tree (dict) – Allowed members per namespace, from build_namespaces

Returns:

• allowed (set of str) – Attribute names that are allowed

• excluded (dict) – Maps each excluded name to (category, reason, label)

• guarded_seen (set of str) – GUARDED_METHODS names found on some object

• unknown_signatures (list of str) – Callables whose signature cannot be inspected

pype_schema.scripts.generate_allowlist.build_namespaces()

Enumerate the allowed members of every namespace in NAMESPACES.

Returns:

• tree (dict) – Maps each namespace path to its allowed names and modules

• excluded (list of tuple) – (category, namespace, name, reason) for each excluded member

• unknown_signatures (list of str) – Callables whose signature cannot be inspected

pype_schema.scripts.generate_allowlist.check_block(source, result, versions_now)

Compare the generated block with what this environment generates.

Parameters:

• source (str) – The text of operations.py

• result (dict or None) – The output of generate; not used if the environment differs

• versions_now (str) – The versions of this environment, from versions_string

Returns:

• code (int) – CHECK_OK, CHECK_DRIFT, or CHECK_WRONG_ENV

• message (str) – What to tell the user

Raises:

ValueError – When the BEGIN/END markers are missing from source

pype_schema.scripts.generate_allowlist.classify_member(ns, name, obj, unknown_signatures)

Decide whether a library member is excluded.

Parameters:

• ns (tuple of str) – The namespace the member is in, such as ("numpy", "linalg")

• name (str) – The member’s name

• obj (object) – The member itself

• unknown_signatures (list of str) – Collects callables whose signature cannot be inspected (changed in place)

Returns:

(category, reason) if the member is excluded

Return type:

tuple or None

pype_schema.scripts.generate_allowlist.default_target(here)

Where operations.py is, relative to the generator.

Parameters:

here (str) – The folder that contains the generator

Returns:

The first of ../operations.py and ../pype_schema/operations.py that exists

Return type:

str

pype_schema.scripts.generate_allowlist.executable_source(obj)

Source of a function or method written in Python, without docstrings.

Parameters:

obj (callable) – The function, method, or class to read

Returns:

The source, or None if it is not available (for example compiled code)

Return type:

str or None

pype_schema.scripts.generate_allowlist.extract_block(source)

The generated block, markers included, inside the text of operations.py.

Parameters:

source (str) – The text of operations.py

Returns:

The block

Return type:

str

Raises:

ValueError – When the BEGIN/END markers are missing

pype_schema.scripts.generate_allowlist.find_parallel(tree)

Allowed library callables that accept a workers-style argument.

Parameters:

tree (dict) – Allowed members per namespace: path -> names and modules

Returns:

Dotted names such as scipy.optimize.differential_evolution

Return type:

list of str

pype_schema.scripts.generate_allowlist.generate()

Run the whole pipeline.

Returns:

Everything needed to render or test the lists: tree, member_excl, attrs, attr_excl, guarded_seen, unknown_sigs, and parallel

Return type:

dict

pype_schema.scripts.generate_allowlist.inject_block(source, block)

Replace the generated block in the text of operations.py.

Parameters:

• source (str) – The text of operations.py

• block (str) – The new block, markers included

Returns:

source with its block replaced

Return type:

str

Raises:

ValueError – When the BEGIN/END markers are missing from source

pype_schema.scripts.generate_allowlist.io_params(obj)

The file-like parameter names of a callable.

Parameters:

obj (callable) – The function or class to inspect

Returns:

Parameters that look like they take a file, or None if there is no signature

Return type:

set of str or None

pype_schema.scripts.generate_allowlist.is_installed_path(path)

Whether a path is inside an installed package, not a source checkout.

Parameters:

path (str) – A file path

Returns:

True for a path under site-packages or dist-packages

Return type:

bool

pype_schema.scripts.generate_allowlist.main()

Rewrite the generated block, or check it with --check.

Raises:

SystemExit – With the --check result as the exit code, or when asked to rewrite an installed copy

pype_schema.scripts.generate_allowlist.match_name_rules(name, scope)

The first NAME_RULES entry that excludes a name.

Parameters:

• name (str) – The member or attribute name

• scope (str) – "module" for library members, "attr" for attributes of ordinary objects

Returns:

(category, reason) of the first matching rule

Return type:

tuple or None

pype_schema.scripts.generate_allowlist.normalize_versions(versions)

Compare Python by major.minor and the libraries exactly.

Parameters:

versions (str or None) – A versions string, such as the one in a generated block’s header

Returns:

versions without the Python patch number

Return type:

str

pype_schema.scripts.generate_allowlist.public_members(module)

Public members of a module, with deprecated ones marked.

Parameters:

module (module) – The module to list

Returns:

Maps each public name to its object, or to a Deprecated marker if reading it warns or fails

Return type:

dict

pype_schema.scripts.generate_allowlist.render_block(tree, attrs, versions)

The exact text of the generated block, markers included.

Parameters:

• tree (dict) – Allowed members per namespace: path -> names and modules

• attrs (iterable of str) – Allowed attribute names

• versions (str) – The environment recorded in the block’s header

Returns:

The block, which is identical for identical inputs

Return type:

str

pype_schema.scripts.generate_allowlist.render_node(ns, tree, depth)

Source code for one namespace’s _ns(...) call, including its submodules.

Parameters:

• ns (tuple of str) – The namespace path

• tree (dict) – Allowed members per namespace: path -> names and modules

• depth (int) – Nesting level, used for indentation

Returns:

The source code

Return type:

str

pype_schema.scripts.generate_allowlist.render_report(tree, member_excl, attr_excl, guarded_seen, attrs, unknown_sigs, parallel)

The Markdown report of what is allowed and what was excluded, and why.

Parameters:

• tree (dict) – Allowed members per namespace: path -> names and modules

• member_excl (list of tuple) – Excluded library members, (category, namespace, name, reason)

• attr_excl (dict) – Excluded attribute names, mapping to (category, reason, label)

• guarded_seen (set of str) – Guarded methods that were found

• attrs (set of str) – Allowed attribute names

• unknown_sigs (list of str) – Callables whose signature cannot be inspected

• parallel (list of str) – Callables that accept a parallelism argument

Returns:

The report

Return type:

str

pype_schema.scripts.generate_allowlist.resolve_namespace(ns)

The module object for a namespace path.

Parameters:

ns (tuple of str) – A namespace path such as ("numpy", "emath")

Returns:

The module that ns names

Return type:

module

pype_schema.scripts.generate_allowlist.sample_results()

Result objects returned by functions, so their field names are seen.

Returns:

Instances such as the results of linregress or minimize

Return type:

list

pype_schema.scripts.generate_allowlist.source_verdict(obj)

Whether the source of a function does something that is excluded.

Parameters:

obj (callable) – The function, method, or class to scan

Returns:

(category, reason) if the source matches a SOURCE_RULES pattern

Return type:

tuple or None

pype_schema.scripts.generate_allowlist.tree_from_frozen(allowed_module_members)

Flatten the nested ALLOWED_MODULE_MEMBERS into one entry per namespace.

Parameters:

allowed_module_members (dict) – ALLOWED_MODULE_MEMBERS as defined in operations.py

Returns:

Maps each namespace path to its names and modules, like build_namespaces

Return type:

dict

pype_schema.scripts.generate_allowlist.versions_string()

The Python, numpy, pandas, and scipy versions of this environment.

Returns:

For example "Python 3.12.3, numpy 2.4.4, pandas 3.0.2, scipy 1.17.1"

Return type:

str

Module contents

Scripts for PyPES developers provided to end users for transparency and reproducibility.