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 = {'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 = {'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 = {'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 = {'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 = {'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 = {}: 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 = {'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 = {'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])

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

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

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

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

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

get_tags()

Get the list of file tags

Return type:: List[str]

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

get_file(file_name)

Get file locally and return its path

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

try_get_file(file_name)

Get file and, if no strategy works, return None

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

prefetch_files_by_list(file_names, skip_disabled=False)

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

Parameters:

file_names (Iterable[str])
skip_disabled (bool)

prefetch_files_by_tag(tag, skip_disabled=False)

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

Parameters:

tag (str)
skip_disabled (bool)

prefetch_all_files(discarded_tags=None, skip_disabled=False)

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

Parameters:

discarded_tags (list[str] | None)
skip_disabled (bool)

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

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

Parameters:: file (PathLike)

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

Bases: BaseModel

Representation of the file registry.

Parameters:

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

get_repository(name)

Get a repository by its name

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

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_tags()

Get the list of known file tags

Return type:: List[str]

model_config = {}: 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 TypeVar(‘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]])

static 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]]

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

disable_file_tags(*tags)

Disable files associated to given tags

Parameters:: tags (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 “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