API Reference

Citations

few.utils.citations:

This module is used to collect citations for all modules in the package. This module is then imported to add citations to module classes using their citation attribute.

class few.utils.citations.HyphenUnderscoreAliasModel

Bases: BaseModel

Pydantic model were hyphen replace underscore in field names.

model_config: ClassVar[ConfigDict] = {'alias_generator': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>, 'extra': 'ignore', 'frozen': True, 'hyphen_replace': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class few.utils.citations.Author(*, family_names, given_names, orcid=None, affiliation=None, email=None)

Bases: HyphenUnderscoreAliasModel

Description of a reference author.

Parameters:

family_names (str)
given_names (str)
orcid (str | None)
affiliation (str | None)
email (str | None)

model_config: ClassVar[ConfigDict] = {'alias_generator': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>, 'extra': 'ignore', 'frozen': True, 'hyphen_replace': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class few.utils.citations.Publisher(*, name)

Bases: HyphenUnderscoreAliasModel

Description of a publisher.

Parameters:: name (str)

model_config: ClassVar[ConfigDict] = {'alias_generator': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>, 'extra': 'ignore', 'frozen': True, 'hyphen_replace': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class few.utils.citations.Identifier(*, type, value, description=None)

Bases: HyphenUnderscoreAliasModel

Description of an identifier.

Parameters:

type (str)
value (str)
description (str | None)

model_config: ClassVar[ConfigDict] = {'alias_generator': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>, 'extra': 'ignore', 'frozen': True, 'hyphen_replace': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class few.utils.citations.ReferenceABC

Bases: HyphenUnderscoreAliasModel, ABC

Abstract base class for references.

abstractmethod to_bibtex()

Convert a reference object to a BibTeX string representation.

Return type:: str

model_config: ClassVar[ConfigDict] = {'alias_generator': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>, 'extra': 'ignore', 'frozen': True, 'hyphen_replace': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class few.utils.citations.ArxivIdentifier(*, reference, primary_class=None)

Bases: BaseModel

Class representing an arXiv identifier

Parameters:

reference (str)
primary_class (str | None)

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class few.utils.citations.ArticleReference(*, abbreviation, authors, title, journal, year, month=None, issue=None, publisher=None, pages=None, start=None, issn=None, doi=None, identifiers=None)

Bases: ReferenceABC

Description of an article.

Parameters:

abbreviation (str)
authors (List[Author])
title (str)
journal (str)
year (int)
month (int | None)
issue (int | None)
publisher (Publisher | None)
pages (int | None)
start (int | None)
issn (str | None)
doi (str | None)
identifiers (List[Identifier] | None)

property arxiv_preprint: ArxivIdentifier | None

Detect an arXiv identifier if any.

an arXiv identifier is: - an identifier of type “other” - which starts with “arxiv:” (case insensitive) - whose second part is either:

The arXiv reference (e.g. “arxiv:1912.07609”)

The primary class followed by ‘/’ and the reference (e.g. “arxiv:gr-qc/1912.07609”)

to_bibtex()

Build the BibTeX representation of an article.

Return type:: str

model_config: ClassVar[ConfigDict] = {'alias_generator': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>, 'extra': 'ignore', 'frozen': True, 'hyphen_replace': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class few.utils.citations.SoftwareReference(*, authors, title, license=None, url=None, repository=None, identifiers=None, year=None, month=None, version=None)

Bases: ReferenceABC

Description of a Software

Parameters:

authors (list[Author])
title (str)
license (str | None)
url (str | None)
repository (str | None)
identifiers (List[Identifier] | None)
year (int | None)
month (int | None)
version (str | None)

property doi: str | None: Return the first DOI in identifiers if any

to_bibtex()

Build the BibTeX representation of a software.

Return type:: str

model_config: ClassVar[ConfigDict] = {'alias_generator': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>, 'extra': 'ignore', 'frozen': True, 'hyphen_replace': <function HyphenUnderscoreAliasModel.Config.hyphen_replace>}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class few.utils.citations.REFERENCE(*values): Bases: Enum

few.utils.citations.build_citation_registry()

Read the package CITATION.cff and build the corresponding registry.

Return type:: CitationRegistry

class few.utils.citations.Citable

Bases: object

Base class for classes associated with specific citations.

classmethod citation()

Return the module references as a printable BibTeX string.

Return type:: str

classmethod module_references()

Method implemented by each class to define its list of references

Return type:: List[REFERENCE | str]

File manager

class few.files.FileManager(config=None)

Bases: object

File manager: handles file download and integrity checks.

Parameters:: config (Optional[Configuration])

build_local_cache(): Add to cache all local files from the registry.

property download_dir: Path: Directory in which downloaded files are written.

get_file(file_name)

Get file locally and return its path

Parameters:: file_name (str)
Return type:: Path

get_tags()

Get the list of file tags

Return type:: List[str]

open(file, mode='r', **kwargs)

Wrapper for open() built-in with automatic file download if needed.

Parameters:: file (PathLike)

property options: FileManagerOptions: Get options of this file manager

prefetch_all_files(): Ensure all files defined in registry are locally present (or raise errors)

prefetch_files_by_list(file_names)

Ensure all files in the given list are present (or raise errors for missing files)

Parameters:: file_names (Iterable[str])

prefetch_files_by_tag(tag)

Ensure all files matching a given tag are locally present (or raise errors)

Parameters:: tag (str)

property registry: FileRegistry: Get the registry of this file manager

property storage_dir: Path: Directory in which files can be read or written.

try_get_local_file(file_name, use_cache=False)

Try to get file locally and return its path

Parameters:

file_name (str)
use_cache (bool)

Return type:

Path | None

class few.files.FileRegistry(*, repositories, files)

Bases: BaseModel

Representation of the file registry.

Parameters:

repositories (List[Repository])
files (List[File])

get_file(name)

Get a file by its name

Parameters:: name (str)
Return type:: File | None

get_files_by_tag(tag)

Get files of given tag

Parameters:: tag (str)
Return type:: Iterator[File]

get_repository(name)

Get a repository by its name

Parameters:: name (str)
Return type:: Repository | None

get_tags()

Get the list of known file tags

Return type:: List[str]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Configuration

Implementation of a centralized configuration management for FEW.

class few.utils.config.ConfigSource(*values)

Bases: Enum

Enumeration of config option sources.

DEFAULT = 'default': Config value comes from its default value

CFGFILE = 'config_file': Config value comes from the configuration file

ENVVAR = 'environment_var': Config value comes from environment variable

CLIOPT = 'command_line': Config value comes from command line parameter

SETTER = 'setter': Config value set by config setter after importing FEW

class few.utils.config.ConfigEntry(label, description, type=~T, default=None, cfg_entry=None, env_var=None, cli_flags=None, cli_kwargs=None, convert=None, validate=<function ConfigEntry.<lambda>>, overwrite=<function ConfigEntry.<lambda>>)

Bases: Generic[T]

Description of a configuration entry.

Parameters:

label (str)
description (str)
type (TypeVar)
default (T | None)
cfg_entry (str | None)
env_var (str | None)
cli_flags (str | List[str] | None)
cli_kwargs (Dict[str, Any] | None)
convert (Callable[[str], T])
validate (Callable[[T], bool])
overwrite (Callable[[T, T], T])

label: str: How the entry is referred to in Python code (config.get(“label”))

description: str: Description of the configuration entry

type

Type of the value

alias of T

default: T | None = None: Default value

cfg_entry: str | None = None: Name of the entry in a config file

env_var: str | None = None: Entry corresponding env var (uppercase, without FEW_ prefix)

cli_flags: str | List[str] | None = None: Flag(s) for CLI arguments of this entry (e.g. “-f”)

cli_kwargs: Dict[str, Any] | None = None: Supplementary arguments to argparse add_argument method for CLI options

convert: Callable[[str], T] = None: Method used to convert a user input to expected type

validate(): Method used to validate the provided option value

overwrite(new): Method used to update the value if given by multiple means

class few.utils.config.ConfigItem(value, source)

Bases: Generic[T]

Actual configuration entry with its run-time properties (value, source, …)

Parameters:

value (T)
source (ConfigSource)

class few.utils.config.ConfigConsumer(config_file=None, env_vars=None, cli_args=None, set_args=None)

Bases: ABC

Base class for actual configs.

This class handles building config values from default, file, environment and CLI options. It keeps a list of unused parameters for an other consumer.

Parameters:

config_file (Union[os.PathLike, Mapping[str, str], None])
env_vars (Optional[Mapping[str, str]])
cli_args (Optional[Sequence[str]])
set_args (Optional[Dict[str, Any]])

abstractmethod classmethod config_entries()

Return the list of the class config entries

Return type:: List[ConfigEntry]

get_extras()

Return extra file, env and cli entries for other consumer.

Return type:: Tuple[Mapping[str, str], Mapping[str, str], Sequence[str]]

few.utils.config.userstr_to_bool(user_str)

Convert a yes/no, on/off or true/false to bool.

Parameters:: user_str (str)
Return type:: bool | None

few.utils.config.userinput_to_pathlist(user_input)

Convert a user input to a list of paths

Return type:: List[Path]

few.utils.config.userinput_to_strlist(user_input)

Convert a user input to a list of paths

Return type:: List[str]

class few.utils.config.InitialConfigConsumer(env_vars=None, cli_args=None)

Bases: ConfigConsumer

Class implementing first-pass config consumer.

On first pass, we only detect if there are CLI arguments which disable config file or environment variables.

Parameters:

env_vars (Optional[Mapping[str, str]])
cli_args (Optional[Sequence[str]])

get_extras()

Return extra file, env and cli entries for other consumer.

Return type:: Tuple[Mapping[str, str], Mapping[str, str], Sequence[str]]

static config_entries()

Return the list of the class config entries

Return type:: List[ConfigEntry]

class few.utils.config.Configuration(config_file=None, env_vars=None, cli_args=None, set_args=None)

Bases: ConfigConsumer

Class implementing FEW complete configuration for the library.

Parameters:

config_file (Union[os.PathLike, Mapping[str, str], None])
env_vars (Optional[Mapping[str, str]])
cli_args (Optional[Sequence[str]])
set_args (Optional[Dict[str, Any]])

get_extras()

Return extra file, env and cli entries for other consumer.

Return type:: Tuple[Mapping[str, str], Mapping[str, str], Sequence[str]]

static config_entries()

Return the list of the class config entries

Return type:: List[ConfigEntry]

build_cli_parent_parsers()

Build a Parser that can be used as parent parser from CLI-specific parsers

Return type:: List[ArgumentParser]

few.utils.config.detect_cfg_file()

Test common path locations for config and return highest-priority existing one (if any).

Return type:: Path | None

Global state

Definition of global states (logger, config, file manager, fast backend, …)

class few.utils.globals.ConfigurationSetter(finalizer=None)

Bases: object

Helper class to define configuration options.

Parameters:: finalizer (Optional[Callable[[Dict[str, Any]], None]])

enable_backends(*backends)

Enable one or multiple backends

Parameters:: backends (str)
Return type:: ConfigurationSetter

set_log_level(level)

Set a specific log level

Parameters:: level (str | int)
Return type:: ConfigurationSetter

set_storage_path(path)

Modify the storage path

Parameters:: path (PathLike)
Return type:: ConfigurationSetter

set_log_format(format)

Change the log format

Parameters:: format (str)
Return type:: ConfigurationSetter

set_file_registry_path(registry_path)

Set the file registry to use

Parameters:: registry_path (PathLike)
Return type:: ConfigurationSetter

set_file_download_path(path)

Set the download path

Parameters:: path (PathLike)
Return type:: ConfigurationSetter

enable_file_download()

Authorize the file manager to download missing files

Return type:: ConfigurationSetter

disable_file_download()

Authorize the file manager to download missing files

Return type:: ConfigurationSetter

set_file_integrity_check(when)

Define when integrity checks should be performed (never, once, always)

Parameters:: when (str)
Return type:: ConfigurationSetter

add_file_extra_paths(*paths)

Add supplementary research paths to file manager

Parameters:: paths (List[PathLike])
Return type:: ConfigurationSetter

get_args()

Get a dictionnary of set options.

Return type:: dict[str, Any]

finalize(): Finalize FEW initialization with specified parameters.

few.utils.globals.get_logger()

Get FEW logger

Return type:: Logger

few.utils.globals.get_file_manager()

Get FEW File Manager

Return type:: FileManager

few.utils.globals.get_config()

Get FEW configuration

Return type:: Configuration

few.utils.globals.get_config_setter(reset=False)

Get a configuration setter.

Parameters:: reset (bool)
Return type:: ConfigurationSetter

few.utils.globals.get_backend(backend_name)

Get a backend by its name.

If the backend name is “cuda”, return a CUDA backend if any available. If the backend name is “gpu”, return a GPU backend if any available.

Parameters:: backend_name (str)
Return type:: Backend

few.utils.globals.get_first_backend(backend_names)

Get the first available backend from a list of backend names

Parameters:: backend_names (Sequence[str])
Return type:: Backend

few.utils.globals.has_backend(backend_name)

Test if a backend is available.

If the backend name is “cuda”, return true if any of “cuda11x” or “cuda12x” is available. If the backend name is “gpu”, return true if any GPU backend is available.

Parameters:: backend_name (str)
Return type:: bool

few.utils.globals.initialize(*cli_args): Initialize FEW configuration, logger and file manager with CLI arguments