scholar_flux.package_metadata package

Submodules

scholar_flux.package_metadata.directories module

The scholar_flux.package_metadata.directories module implements PackageDirectorySettings for directory settings.

This model is initialized on package startup at the package level, using the PackageDirectorySettings.get_default_writable_directory method to determine the default directory to use for caching and logging based on whether it is writable.

class scholar_flux.package_metadata.directories.PackageDirectorySettings(*, hidden_directory_name: str = <factory>, package_directory: ~pathlib._local.Path = <factory>, home_env_var: str = 'SCHOLAR_FLUX_HOME')[source]

Bases: BaseModel

Directory configuration settings used during package initialization to determine writable package directories.

Parameters:

  • hidden_directory_name (str) – The name of the hidden directory for package data where files will be stored.

  • package_directory (Path) – The path to the scholar-flux package directory.

  • home_env_var (str) – The name of the environment variable used to determine the parent directory for the package.

DEFAULT_PACKAGE_NAME: ClassVar[str] = 'scholar_flux'
DEFAULT_PACKAGE_SOURCE_DIRECTORY: ClassVar[Path] = PosixPath('/home/runner/work/scholar-flux/scholar-flux/src/scholar_flux')
get_default_writable_directory(directory_type: Literal['package_cache', 'logs', 'env'], subdirectory: str | Path | None = None, *, default: Path | None = None) → Path[source]

Determines the default directory to use for storing package cache, logs, and environment variables.

In the case where a default directory is not specified for caching and logging in package-specific functionality, this method serves as a fallback, identifying writable package directories when required.

Parameters:

  • directory_type (Literal['package_cache','logs', "env"]) – The functionality that a writable directory is being created for.

  • subdirectory (Optional[str | Path]) – The name or folder path to create within the default directory. By default, the scholar_flux package creates package_cache and logs subdirectories for caching and logging, respectively, while environment variables are read directly from a .env file if placed within the parent directory.

  • default (Optional[Path]) – Defines an optional path to use when none of the default directories are available. If None, this function will raise a RuntimeError when the package default directories are not writable.

Returns:

The path of a default writable directory if found.

Return type:

Path

Raises:

RuntimeError if a writable directory cannot be identified. –

hidden_directory_name: str
home_env_var: str
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

package_directory: Path
property package_env_home: Path | None

Resolves the user-specified package home_env variable for storing logs, caching, and configuration.

classmethod verify_directory(path: str | Path, create_parent_directories: bool = False) → Path[source]

Uses pathlib.Path to verify that the current directory is writable by attempting to create the directory.

Parameters:

  • path (str| Path) – The directory to check. The string paths are converted into a pathlib.Path objects before directory verification.

  • create_parent_directories (bool) – Indicates whether parent directories should be created if they do not already exist.

Returns:

The original path if the directory is writable.

Return type:

Path

Raises:

  • PermissionError – If the directory is not writable due to a permissions error.

  • OSError – If an OSError occurs when attempting to create the directory.

  • TypeError – If an incorrect type is passed to Path or Path.mkdir.

Module contents

The scholar_flux.package_metadata module is a helper module that holds information relevant to the initialization and storage of data related to the scholar_flux package.

At the moment, the package_metadata module has two responsibilities:

  1. Retrieving the current version number of the scholar_flux package from the importlib module

  2. Indicating the first available writable directory dedicated to scholar_flux cache.

For directory cache, the following directories are prioritized in the following order:

  1. The scholar_flux/package_directory for cache and scholar_flux/logs for logging

Otherwise:

  1. The ~/.scholar_flux/package_cache directory for cache and ~/.scholar_flux/logs for logging

The first writable directory will then be used for setting up default locations for requests and response cache.

class scholar_flux.package_metadata.PackageDirectorySettings(*, hidden_directory_name: str = <factory>, package_directory: ~pathlib._local.Path = <factory>, home_env_var: str = 'SCHOLAR_FLUX_HOME')[source]

Bases: BaseModel

Directory configuration settings used during package initialization to determine writable package directories.

Parameters:

  • hidden_directory_name (str) – The name of the hidden directory for package data where files will be stored.

  • package_directory (Path) – The path to the scholar-flux package directory.

  • home_env_var (str) – The name of the environment variable used to determine the parent directory for the package.

DEFAULT_PACKAGE_NAME: ClassVar[str] = 'scholar_flux'
DEFAULT_PACKAGE_SOURCE_DIRECTORY: ClassVar[Path] = PosixPath('/home/runner/work/scholar-flux/scholar-flux/src/scholar_flux')
get_default_writable_directory(directory_type: Literal['package_cache', 'logs', 'env'], subdirectory: str | Path | None = None, *, default: Path | None = None) → Path[source]

Determines the default directory to use for storing package cache, logs, and environment variables.

In the case where a default directory is not specified for caching and logging in package-specific functionality, this method serves as a fallback, identifying writable package directories when required.

Parameters:

  • directory_type (Literal['package_cache','logs', "env"]) – The functionality that a writable directory is being created for.

  • subdirectory (Optional[str | Path]) – The name or folder path to create within the default directory. By default, the scholar_flux package creates package_cache and logs subdirectories for caching and logging, respectively, while environment variables are read directly from a .env file if placed within the parent directory.

  • default (Optional[Path]) – Defines an optional path to use when none of the default directories are available. If None, this function will raise a RuntimeError when the package default directories are not writable.

Returns:

The path of a default writable directory if found.

Return type:

Path

Raises:

RuntimeError if a writable directory cannot be identified. –

hidden_directory_name: str
home_env_var: str
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

package_directory: Path
property package_env_home: Path | None

Resolves the user-specified package home_env variable for storing logs, caching, and configuration.

classmethod verify_directory(path: str | Path, create_parent_directories: bool = False) → Path[source]

Uses pathlib.Path to verify that the current directory is writable by attempting to create the directory.

Parameters:

  • path (str| Path) – The directory to check. The string paths are converted into a pathlib.Path objects before directory verification.

  • create_parent_directories (bool) – Indicates whether parent directories should be created if they do not already exist.

Returns:

The original path if the directory is writable.

Return type:

Path

Raises:

  • PermissionError – If the directory is not writable due to a permissions error.

  • OSError – If an OSError occurs when attempting to create the directory.

  • TypeError – If an incorrect type is passed to Path or Path.mkdir.

scholar_flux.package_metadata.get_default_writable_directory(directory_type: Literal['package_cache', 'logs', 'env'], subdirectory: str | Path | None = None, *, default: Path | None = None) → Path

Determines the default directory to use for storing package cache, logs, and environment variables.

In the case where a default directory is not specified for caching and logging in package-specific functionality, this method serves as a fallback, identifying writable package directories when required.

Parameters:

  • directory_type (Literal['package_cache','logs', "env"]) – The functionality that a writable directory is being created for.

  • subdirectory (Optional[str | Path]) – The name or folder path to create within the default directory. By default, the scholar_flux package creates package_cache and logs subdirectories for caching and logging, respectively, while environment variables are read directly from a .env file if placed within the parent directory.

  • default (Optional[Path]) – Defines an optional path to use when none of the default directories are available. If None, this function will raise a RuntimeError when the package default directories are not writable.

Returns:

The path of a default writable directory if found.

Return type:

Path

Raises:

RuntimeError if a writable directory cannot be identified. –