prometa package

Subpackages

Submodules

prometa.citation module

Citation file format (.cff) functions.

https://citation-file-format.github.io/ https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md

class prometa.citation.Citation(project)[source]

Bases: object

Citation data manager.

__init__(project)[source]

Parameters:: project – A Project instance.

static get_template()[source]: Get the cff file template as an object.

update()[source]

Update the citation file with data from codemeta.json and other sources.

Returns:: The citation file object.

prometa.common module

Common constants.

prometa.config module

Configuration.

class prometa.config.Config(proj_path, custom_config_paths=None, use_xdg=True, **overrides)[source]

Bases: object

Common non-derivable configuration.

__init__(proj_path, custom_config_paths=None, use_xdg=True, **overrides)[source]

Parameters:

proj_path – The project path.
custom_config_paths – An iterable over custon configuration file paths to use in addition to the standard configuration files that Prometa normally detects.
use_xdg – If True, search for configuration files in standard XDG configuration directories. These files will be given the lowest priority.
**overrides – Custom run-time overrides that take precedence over values in all discovered configuration files.

property config[source]

The configuration file object. If None, there is no configuration file.

Raises:: ConfigError – One of the configuration files failed to load.

property config_paths[source]: A generator over existing configuration paths. It is a wrapper around possible_config_paths that checks for and logs existence.

get(*keys, default=None)[source]

Retrieve a configuration file value. This will scan the loaded configuration files in order and return the first match.

Parameters:

*keys – The keys to the field. For example, to retrieve the value of “bar” under “foo”, call get(“foo”, “bar”). Integers may also be used to index lists.
default – The default value to return if no value was found.

Returns:

The target value, or the default if no value was found.

property gitlab[source]: The python-gitlab GitLab instance from the current configuration.

property possible_config_paths[source]

A generator over the possible configuration file paths. Custom paths are yielded first, in the order they were given. Next the possible visible and hidden configuration paths in the current project directory and all of its parent directories are yielded, starting with the project directory and moving up to the root directory. Finally, if use_xdg is True, the standard XDG configuration directories are yielded, again in the standard order.

The generator does not check if the paths exist but it will omit duplicate paths.

exception prometa.config.ConfigError[source]

Bases: PrometaException

Custom error raised by the Config class.

prometa.exception module

Exceptions.

exception prometa.exception.PrometaException[source]

Bases: Exception

Base class for custom exceptions.

prometa.file module

File operations.

prometa.file.diff(path_1, path_2, differ='vimdiff')[source]: Diff 2 paths.

prometa.file.update_content(content, path, encoding='utf-8', **kwargs)[source]

Interactively compare and merge new content. If the target path does not exist, the content will be written directly to it.

Parameters:

content – The new content to merge.
path – The target path.
encoding – The file encoding to use when writing the content. If None, the content is assumed to be bytes.
**kwargs – Keyword arguments passed through to diff().

prometa.insert module

Base class for inserting content into text files.

class prometa.insert.Inserter(regex)[source]

Bases: object

Insert updated content into a text file.

__init__(regex)[source]

Parameters:: regex – A compiled regular expression.

insert(match)[source]

Given a regular expression match, return the content to insert.

Parameters:: match – The Match object.
Returns:: The string to substitute for the match.

update(path, encoding='utf-8')[source]: Insert the configured content into the file.

class prometa.insert.MarkdownInserter[source]

Bases: Inserter

Inserter with custom regex for invisible comments in Markdown files.

In Markdown, a link label for a simple hash results in no output for most common Markdown processors: “[comment]: #”. Note that these must be proceeded by blank lines to be recognized in Markdown.

This class recognized blocks that begin with a comment prefixed with “insert: “ and end with a comment containing only “/insert”. Both comments must have the same indentation level and the inserted text will be indented to the same level.

__init__()[source]

Parameters:: regex – A compiled regular expression.

static get_link(label, url)[source]

Get the Markdown link.

Parameters:

label – The label shown for the link.
url – The URL of the link.

Returns:

The Markdown link as a string.

get_output(label, content)[source]

Get output to replace the given label. Override this to insert custom content.

Parameters:

label – The label in the comment pair that was matched.
content – The content between the matched comments.

Returns:

The content to insert, or None if the label was not recognized.

insert(match)[source]

Given a regular expression match, return the content to insert.

Parameters:: match – The Match object.
Returns:: The string to substitute for the match.

prometa.main module

Update project metadata.

prometa.main.configure_logging(level=20)[source]

Configure logging.

Parameters:: level – The logging level.

prometa.main.main(args=None)[source]: Main function.

prometa.main.run_main(args=None)[source]: Wrapper around main for exception handling.

prometa.project module

Project class.

class prometa.project.Project(path, **config_kwargs)[source]

Bases: object

Project class.

__init__(path, **config_kwargs)[source]

Parameters:

path – The path to the project.
**config_kwargs – Keyword arguments passed through to Config.

property citation_cff_path[source]: The path to the CITATION.cff file.

property codemeta_json_path[source]: The path to the codemeta.json file.

property license_txt_path[source]: The path to the LICENSE.txt file.

property name[source]: The project name. It will use the value in codemeta.name if it exists, otherwise it will use the name of the project’s directory.

property readme_md_path[source]: The README.md path.

property spdx_license[source]: The detected SPDX license name.

update()[source]: Update project metadata.

property urls[source]: A dict of URLs for the project.

prometa.readme module

Insert data into the README.

class prometa.readme.ReadmeInserter(project)[source]

Bases: MarkdownInserter

Processes several labels to insert various content in the README file.

__init__(project)[source]

Parameters:: regex – A compiled regular expression.

get_output(label, content)[source]: Override parent get_output.

property labels[source]: The dict mapping labels to their methods.

process_label_badges(label, _content)[source]

Insert badges into the README.

Parameters:

label – The insert label (see below).
_content – The current block content.

Returns:

A Markdown string containing badges for the README.

Raises:

PrometaException – A remote API call failed.

`badges <api> [<api> ...]`

Insert all badges currently configured on the project's Git host.
`<api>` specifies the API to use to query the badges. Currently only
the following value is supported.

gitlab
: Insert all badges from the project's remote GitLab instance
origin.  The badges are retrieved via calls to the GitLab API so
this requires the "gitlab" section to be configured in the project's
configuration file (see the configuration section for details).

process_label_citation(label, _content)[source]

Get the section containing citation examples for different targets.

Parameters:

label – The insert label (see below).
_content – The current block content.

Returns:

A Markdown string containing the citations section.

`citations <level>`

Convert CITATIONS.cff to different formats using with
[cffconvert](https://pypi.org/project/cffconvert/) and insert them
into the README.

The `<level>` parameter is an integer to indicate the heading level
of the current context. It will be used to insert nested headers in
the content. If omitted, level 1 is assumed.

process_label_command(label, _content)[source]

Get the output of a command.

Parameters:

label – The insert label (see below).
_content – The current block content.

Returns:

A Markdown string containing the command output (see below for details about how to control the wrapping codeblock). If the user declines the command when prompted, None is returned instead.

Raises:

PrometaException – A CalledProcessError or OSError occurred when running the command.

`command_output[:<lang>] <command string>`

Insert the output of an arbitrary command. The user will be prompted
to confirm the command before it is run to prevent unknowingly
executing arbitrary code, unless Prometa is currently configured to
trust all commands (e.g. via the `--trust` command-line option).

`<command string>` should be a valid shell command string. It will
be interpreted internally using
[shlex.split()](https://docs.python.org/3/library/shlex.html#shlex.split).
The confirmation prompt will show the user the parsed command.

The output will be wrapped in a code block. The user may specify an
optional language for syntax highlighting by appending `:<lang>` to
the end of the `command_output` label, where `<lang>` is the desired
language. For example, to insert YAML output, use
`command_output:yaml command arg1 arg2 ...`.

The command also supports the custom language tag
"embedded_markdown", which will insert the command's output into the
Markdown document directly instead of fencing it in a code block.

process_label_links(label, _content)[source]

Get the section containing standard links.

Parameters:

label – The insert label (see below).
_content – The current block content.

Returns:

A Markdown string containing the links section.

`links <level>`

Insert project links such as homepage, source code repository, issue
tracker, documentation, etc. Optional third-part repository links
(PyPI, SWH, HAL) will also be inserted if Prometa detects that they
contain the project.

The `<level>` parameter is an integer to indicate the heading level
of the current context. It will be used to insert nested headers in
the content. If omitted, level 1 is assumed.

process_label_verbatim(label, content)[source]

Do nothing.

Parameters:

label – The insert label (see below).
content – The current block content.

Returns:

False

`verbatim`

Return the content between the invisible comments as-is. This no-op
label can be used to wrap examples of other labels and anything else
that should not be modified.

prometa.requests module

Convenience functions for the requests package.

prometa.requests.get_json_or_none(url, timeout=5)[source]

Request a URL and return either the JSON response or None if the request failed. An error message will be logged in the latter case.

Parameters:: url – The URL to request. It should return a JSON response.
Returns:: The parsed JSON object, or None if the request failed.

prometa.utils module

Utility functions.

prometa.utils.choose(items, include_none=False)[source]

Prompt the user to choose an item from an iterable of items.

Parameters:

items – The iterable of items.
include_none – If True, allow the user to choose None even if it is not in the list.

Returns:

The chosen item.

prometa.utils.format_docstring_for_cell(docstring)[source]

Format a docstring for a table cell. This just dedents the block, replaces newlines and handles reStructuredText links. At the time of writting, none of the proposed packages for converting docstrings to Markdown worked reliably.

Parameters:: docstring – The docstring.
Returns:: The docstring content as a single-line Markdown string that may contain <br /> tags.

prometa.utils.join_docstrings(delimiter, docstrings)[source]

Join docstrings with a delimiter. The indentation of the last docstring is preserved for the joined docstring.

Parameters:

delimiter – The delimiter to place between the docstrings. If None, no delimiter is emitted.
docstrings – A list of docstrings.

Returns:

The docstring that results from joining the docstrings.

prometa.utils.prepend_docstrings(delimiter, *objects)[source]

Decorator to prepend docstrings to an object’s docstring.

Parameters:

delimiter – The delimiter to pass to join_docstrings.
objects – The objects from which to retrieve the docstrings.

Module contents

Package stub.