texgit.repository package

Interaction with repositories and processes.

Submodules

texgit.repository.file_manager module

A class for managing files and directories.

A FileManager provides a two-level abstraction for assigning paths to unique IDs. An ID is a combination of a “realm” and a “name”, both of which are non-empty strings without whitespace.

A file manager resides within a certain base directory. Inside the base directory, it provides so-called “realms”. Each realm is a separate namespace. With a realm, “names” are mapped to paths. The file manager ensures that the same realm-name combination is always assigned to the same path. The first time such a combination is queried, the path is created. This path can be a file or a directory, depending on what was queried. Every realm-name combination always uniquely identifies a path and there can never be another realm-name combination pointing to the same path. If need be, the paths are randomized to avoid potential clashes.

Once the file manager is closed, the realm-name to path associations are stored. When a new file manager instance is created for the same base directory, the associations of realms-names to paths are restored. This means that a program that creates output files for certain commands can then find these files again later.

GitManager is the base and root of the functionality of a managed repository of files and data. Step-by-step, functionality is added to the manager by derived classes. We do this iteratively:

GitManager adds the capability to automatically download and use git repositories. For this purpose, it uses the realm git.

ProcessManager adds the ability to execute programs or scripts and to store their output in files to the GitManager. These programs and scripts may be located in git repositories that have automatically been downloaded.

class texgit.repository.file_manager.FileManager(base_dir)[source]

Bases: AbstractContextManager

A manager for files.

close()[source]

Close the file manager and write cache list.

Return type:

None

get_dir(realm, name)[source]

Get a directory representing the given name in the given realm.

Parameters:

  • realm (str) – the realm

  • name (str) – the name or ID that the directory should represent

Return type:

tuple[Path, bool]

Returns:

the directory path and a bool indicating whether it was newly generated (True) or not if it already existed (False)

get_file(realm, name, prefix=None, suffix=None)[source]

Get a file representing the given name in the given realm.

Parameters:

  • realm (str) – the realm

  • name (str) – the name or ID that the file should represent

  • prefix (str | None, default: None) – the optional prefix

  • suffix (str | None, default: None) – the optional suffix

Return type:

tuple[Path, bool]

Returns:

the generated file path and True if it was new, or False if not.

list_realm(realm, files=True, directories=True)[source]

List all the files and directories in a given realm.

Parameters:

  • realm (str) – the realm that we want to list

  • files (bool, default: True) – should we list files?

  • directories (bool, default: True) – should we list directories?

Return type:

tuple[Path, ...]

Returns:

the iterator with the data

texgit.repository.fix_path module

A tool for fixing all occurrences of a Path.

texgit.repository.fix_path.BASE_PATH_REPLACEMENT: Final[str] = '{...}'

the replacement string for base paths

texgit.repository.fix_path.replace_base_path(orig, base_path)[source]

Replace all occurrences of the base_path in the original string.

Any reasonably delimited occurrence of base_path as well as any sub-path under base_path that points to an existing file or directory are replaced with relativizations starting with {…}.

Parameters:

  • orig (str) – the original string

  • base_path (str) – the base path

Return type:

str

Returns:

the fixed string

>>> from pycommons.io.temp import temp_dir
>>> with temp_dir() as td:
...     td.resolve_inside("x").ensure_dir_exists()
...     td.resolve_inside("x/y").write_all_str("5")
...     a = replace_base_path(f"blablabla {td}/x ", td)
...     b = replace_base_path(f"{td}/x/y", td)
...     c = replace_base_path(f"{td}/x.", td)
...     d = replace_base_path("\n".join(("blaa", f"{td}/x.x", "y")), td)
...     e = replace_base_path("\n".join(("blaa", f"{td}/x.", "y")), td)
...     f = replace_base_path(f"xc'{td}/x/y'yy", td)
...     g = replace_base_path(td, td)
...     h = replace_base_path(td + "/", td)
>>> a
'blablabla {...}/x '

>>> b
'{...}/x/y'

>>> c
'{...}/x.'

>>> d[-6:]
'/x.x\ny'

>>> e
'blaa\n{...}/x.\ny'

>>> f
"xc'{...}/x/y'yy"

>>> g
'{...}'

>>> h
'{...}/'

texgit.repository.git module

Tools for interacting with repository.

class texgit.repository.git.GitRepository(path, url, commit, date_time)[source]

Bases: object

An immutable record of a repository.

commit: str

the commit

date_time: str

the date and time

static download(url, dest_dir)[source]

Download a git repository.

Parameters:

  • url (str) – the repository url

  • dest_dir (str) – the destination directory

Return type:

GitRepository

Returns:

the repository information

static from_local(path, url=None)[source]

Load all the information from a local repository.

Parameters:

  • path (str) – the path to the repository

  • url (str | None, default: None) – the url

Return type:

GitRepository

Returns:

the repository information

get_name()[source]

Get the name of this git repository in the form ‘user/name’.

Return type:

str

Returns:

the name of this git repository in the form ‘user/name’.

make_url(path)[source]

Make a url relative to this git repository.

Parameters:

path (str) – the absolute path

Return type:

URL

Returns:

the url

path: Path

the repository path

url: URL

the normalized repository url

texgit.repository.git.git()[source]

Get the path to the git executable.

Return type:

Path

Returns:

the path to the git executable

texgit.repository.git_manager module

A manager for repository repositories.

This class allows to maintain a local stash of repository repositories that can consistently be accessed without loading any repository multiple times.

class texgit.repository.git_manager.GitManager(base_dir)[source]

Bases: FileManager

A git repository manager can provide a set of git repositories.

get_git_dir(repo_url, relative_dir)[source]

Get a path to a directory from the given git repository.

Parameters:

  • repo_url (str) – the repository url.

  • relative_dir (str) – the relative path

Return type:

GitPath

Returns:

a tuple of directory and URL

get_git_file(repo_url, relative_file)[source]

Get a path to a file from the given git repository and also the URL.

Parameters:

  • repo_url (str) – the repository url.

  • relative_file (str) – the relative path

Return type:

GitPath

Returns:

a tuple of file and URL

get_repository(url)[source]

Get the git repository for the given URL.

Parameters:

url (str) – the URL to load

Return type:

GitRepository

Returns:

the repository

class texgit.repository.git_manager.GitPath(path, repo, url, basename=None)[source]

Bases: object

An immutable record of a path inside a git repository.

basename: str

the base name of the file

path: Path

the absolute path of the file or directory inside the repository directory

repo: GitRepository

the repository

url: URL

the URL

texgit.repository.process_manager module

A class for managing files and directories.

A file manager provides a two-level abstraction for assigning names to paths. It exists within a certain base directory. Inside the base directory, it provides so-called “realms”. Each realm is a separate namespace. With a realm, “names” are mapped to paths. The file manager ensures that the same realm-name combination is always assigned to the same path. The first time it is queried, the path is created. This path can be a file or a directory, depending on what was queried. Every realm-name combination always uniquely identifies a path and there can never be another realm-name combination pointing to the same path. The paths are randomized to avoid potential clashes.

Once the file manager is closed, the realm-name to path associations are stored. When a new file manager instance is created for the same base directory, the associations of realms-names to paths are restored. This means that a program that creates output files for certain commands can then find these files again later.

class texgit.repository.process_manager.ProcessManager(base_dir)[source]

Bases: GitManager

A manager for processes.

filter_argument(arg)[source]

Filter an argument to be passed to any given file.

This function can be used to rewire arguments of certain programs that we want to invoke to specific files.

Parameters:

arg (str) – the argument

Return type:

str | None

Returns:

the filtered argument

get_argument_file(name, prefix=None, suffix=None)[source]

Create a file in the argument realm.

Parameters:

  • name (str) – the ID for the file

  • prefix (str | None, default: None) – the optional prefix

  • suffix (str | None, default: None) – the optional suffix

Return type:

tuple[Path, bool]

Returns:

the file, plus a bool indicating whether it was just created (True) or already existed (False)

get_git_file(repo_url, relative_file, name=None, command=None)[source]

Get a path to a postprocessed file from the given git repository.

Parameters:

  • repo_url (str) – the repository url.

  • relative_file (str) – the relative path to the file

  • name (str | None, default: None) – the name for the output

  • command (Union[str, Iterable[str], None], default: None) – the command itself

Return type:

GitPath

Returns:

a tuple of file and URL

get_output(name, command, repo_url=None, relative_dir=None)[source]

Get the output of a certain command.

Parameters:

  • name (str) – the name for the output

  • command (Union[str, Iterable[str]]) – the command itself

  • repo_url (str | None, default: None) – the optional repository URL

  • relative_dir (str | None, default: None) – the optional directory inside the repository where the command should be executed

Return type:

Path

Returns:

the path to the output and, if repo_url and relative_dir were not None, then a URL pointing to the directory in the repository, else None

texgit.repository.process_manager.SYS_ENV: Final[Mapping[str, str]] = mappingproxy({'PATH': '/tmp/tmp.5jawEznwK5/bin:/opt/hostedtoolcache/Python/3.12.12/x64/bin:/opt/hostedtoolcache/Python/3.12.12/x64:/snap/bin:/home/runner/.local/bin:/opt/pipx_bin:/home/runner/.cargo/bin:/home/runner/.config/composer/vendor/bin:/usr/local/.ghcup/bin:/home/runner/.dotnet/tools:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin', 'PYTHONPATH': '/home/runner/work/texgit_py/texgit_py', 'PYTHON_INTERPRETER': '/tmp/tmp.5jawEznwK5/bin/python3', 'VIRTUAL_ENV': '/tmp/tmp.5jawEznwK5', 'LC_CTYPE': 'C.UTF-8', 'DOCUTILSCONFIG': '/home/runner/work/texgit_py/texgit_py/docs/source/docutils.conf'})

the environment that we will pass on