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 and functions.

prometa.common.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.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.

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.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 pyproject_toml_path[source]

The pyproject.toml path.

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

Insert data into the Markdown file.

__init__(project)[source]
Parameters:

regex – A compiled regular expression.

get_output(label, content)[source]

Override parent get_output.

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.

Module contents

Package stub.