acmecse.helpers.CredentialTools

module documentation

(source)

This module provides helper functions for managing credential files, such as username/password files and token files. It allows adding, removing, and checking entries.

Comments and blank lines in the files are preserved, and entries can be updated (upserted) if desired.

Exception	`DuplicateEntryError`	Raised when a duplicate entry is found in a credential file.
Exception	`EntryExistsError`	Raised when attempting to add an entry that already exists without explicitly allowing an overwrite.
Exception	`EntryNotFoundError`	Raised when an entry is not found in a credential file.
Function	`addCredentialEntry`	Add or update a username/password entry in a credential file.
Function	`addEntry`	Add or update (upsert) an entry in a line-based file, preserving existing entries, comments, and blank lines.
Function	`addTokenEntry`	Add or update a token entry in a token file.
Function	`getCredentialEntry`	Retrieve the password for a given username from a credential file.
Function	`hasEntry`	Check whether an entry exists in a line-based file.
Function	`hasTokenEntry`	Check whether a token entry exists in a token file.
Function	`readCredentialFile`	Read a username/password credential file and return a dictionary of entries.
Function	`readTokenFile`	Read a token credential file and return a list of tokens.
Function	`removeCredentialEntry`	Remove a username/password entry from a credential file.
Function	`removeEntry`	Remove an entry from a line-based file, preserving existing entries, comments, and blank lines.
Function	`removeTokenEntry`	Remove a token entry from a token file.
Function	`_findEntryIndex`	Find the index of an entry in a list of lines based on a lookup key.
Function	`_readLines`	Read all lines from a file, stripping whitespace and ignoring comments and blank lines.
Function	`_writeLines`	Write lines to a file, ensuring that the file ends with a newline.

def addCredentialEntry(filePath: str | Path, username: str, password: str, update: bool = False): (source) ¶

Add or update a username/password entry in a credential file.

Parameters
filePath:`str \| Path`	Path to the credential file.
username:`str`	The username for the entry.
password:`str`	The password for the entry.
update:`bool`	If True, perform an upsert — an existing entry is replaced, or a new one added if none exists. If False (default) and the username already exists, an EntryExistsError is raised.

Raises
`EntryExistsError`	If the username already exists and update is False.

def addEntry(filePath: str | Path, key: str, newLine: str, keyOf: Callable[[str], str] = lambda line: line, update: bool = False): (source) ¶

Add or update (upsert) an entry in a line-based file, preserving existing entries, comments, and blank lines.

Parameters
filePath:`str \| Path`	Path to the file.
key:`str`	The lookup key for the entry (e.g. username, or the token itself).
newLine:`str`	The full line to write for this entry.
keyOf:`Callable[[str], str]`	Function that extracts the lookup key from an existing line.
update:`bool`	If True, perform an upsert — an existing entry is replaced, or a new one added if none exists. If False (default) and the key already exists, an EntryExistsError is raised.

Raises
`EntryExistsError`	If the key already exists and update is False.

def addTokenEntry(filePath: str | Path, token: str, update: bool = False): (source) ¶

Add or update a token entry in a token file.

Parameters
filePath:`str \| Path`	Path to the token file.
token:`str`	The token for the entry.
update:`bool`	If True, perform an upsert — an existing entry is replaced, or a new one added if none exists. If False (default) and the token already exists, an EntryExistsError is raised.

Raises
`EntryExistsError`	If the token already exists and update is False.

def getCredentialEntry(filePath: str | Path, username: str) -> str | None: (source) ¶

Retrieve the password for a given username from a credential file.

Parameters
filePath:`str \| Path`	Path to the credential file.
username:`str`	The username for which to retrieve the password.

Returns
`str \| None`	The password for the given username, or None if not found.

def hasEntry(filePath: str | Path, key: str, keyOf: Callable[[str], str] = lambda line: line) -> bool: (source) ¶

Check whether an entry exists in a line-based file.

Parameters
filePath:`str \| Path`	Path to the file.
key:`str`	The lookup key for the entry.
keyOf:`Callable[[str], str]`	Function that extracts the lookup key from an existing line.

Returns
`bool`	True if an entry with the given key exists, False otherwise.

def hasTokenEntry(filePath: str | Path, token: str) -> bool: (source) ¶

Check whether a token entry exists in a token file.

Parameters
filePath:`str \| Path`	Path to the token file.
token:`str`	The token for the entry.

Returns
`bool`	True if an entry with the given token exists, False otherwise.

def readCredentialFile(filePath: str | Path) -> dict[str, str]: (source) ¶

Read a username/password credential file and return a dictionary of entries.

Parameters
filePath:`str \| Path`	Path to the credential file.

Returns
`dict[str, str]`	A dictionary mapping usernames to passwords. If the file does not exist, returns an empty dictionary.

Raises
`DuplicateEntryError`	If there are duplicate usernames in the file.

def readTokenFile(filePath: str | Path) -> list[str]: (source) ¶

Read a token credential file and return a list of tokens.

Parameters
filePath:`str \| Path`	Path to the token file.

Returns
`list[str]`	A list of tokens. If the file does not exist, returns an empty list.

Raises
`DuplicateEntryError`	If there are duplicate tokens in the file.

def removeCredentialEntry(filePath: str | Path, username: str): (source) ¶

Remove a username/password entry from a credential file.

Parameters
filePath:`str \| Path`	Path to the credential file.
username:`str`	The username for the entry to remove.

Raises
`EntryNotFoundError`	If the entry is not found.

def removeEntry(filePath: str | Path, key: str, keyOf: Callable[[str], str] = lambda line: line): (source) ¶

Remove an entry from a line-based file, preserving existing entries, comments, and blank lines.

Parameters
filePath:`str \| Path`	Path to the file.
key:`str`	The lookup key for the entry to remove.
keyOf:`Callable[[str], str]`	Function that extracts the lookup key from an existing line.

Raises
`EntryNotFoundError`	If the entry is not found.

def removeTokenEntry(filePath: str | Path, token: str): (source) ¶

Remove a token entry from a token file.

Parameters
filePath:`str \| Path`	Path to the token file.
token:`str`	The token for the entry to remove.

Raises
`EntryNotFoundError`	If the entry is not found.

def _findEntryIndex(lines: list[str], key: str, keyOf: Callable[[str], str]) -> int | None: (source) ¶

Find the index of an entry in a list of lines based on a lookup key.

Parameters
lines:`list[str]`	List of lines to search.
key:`str`	The lookup key for the entry (e.g. username, or the token itself).
keyOf:`Callable[[str], str]`	Function that extracts the lookup key from an existing line.

Returns
`int \| None`	The index of the entry if found, or None if not found.

def _readLines(filePath: str | Path) -> list[str]: (source) ¶

Read all lines from a file, stripping whitespace and ignoring comments and blank lines.

Parameters
filePath:`str \| Path`	Path to the file.

Returns
`list[str]`	A list of stripped lines from the file. If the file does not exist, returns an empty list.

def _writeLines(filePath: str | Path, lines: list[str]): (source) ¶

Write lines to a file, ensuring that the file ends with a newline.

Parameters
filePath:`str \| Path`	Path to the file.
lines:`list[str]`	List of lines to write to the file.