Downloads the FJC's Biographical Directory of Article III Federal Judges.

The Federal Judicial Center exports its directory every night as six CSV files, one for each category of information about the judges (see https://www.fjc.gov/history/judges/biographical-directory-article-iii-federal-judges-export). They need no account and are a few megabytes together. They are saved under their FJC names in the "raw" folder of the data folder:

data_folder/
└── raw/    demographics.csv, federal-judicial-service.csv, ...

Contents

data_folder: returns the folder where the files are kept. download: downloads the FJC's files. raw_folder: returns the folder of the downloaded files.

data_folder()

Returns the folder where the files are kept.

The folder is the one named by the FJC_BIOGRAPHIES_DATA_DIR environment variable, if it is set. Otherwise, when fjc_biographies runs from its repository, it is options._DATA_FOLDER: "data/courts/fjc_biographies" two folders above the repository, beside the folder of code projects (where courtpy and fjc-idb keep their files as well). When fjc_biographies is installed as a package, it is "fjc_biographies" in the user's local application data folder on Windows ("%LOCALAPPDATA%"), or in "~/.local/share" (or "$XDG_DATA_HOME") on other systems.

Returns:

Type	Description
Path	The path of the folder. It is not created.

Source code in src/fjc_biographies/downloader.py

def data_folder() -> pathlib.Path:
    """Returns the folder where the files are kept.

    The folder is the one named by the `FJC_BIOGRAPHIES_DATA_DIR` environment
    variable, if it is set. Otherwise, when fjc_biographies runs from its
    repository, it is `options._DATA_FOLDER`: "data/courts/fjc_biographies"
    two folders above the repository, beside the folder of code projects
    (where courtpy and fjc-idb keep their files as well). When fjc_biographies
    is installed as a package, it is "fjc_biographies" in the user's local
    application data folder on Windows ("%LOCALAPPDATA%"), or in
    "~/.local/share" (or "$XDG_DATA_HOME") on other systems.

    Returns:
        The path of the folder. It is not created.

    """
    named = os.environ.get(options._ENV_DATA)
    if named:
        return pathlib.Path(named).expanduser()
    if (pathlib.Path(__file__).parents[2] / 'pyproject.toml').is_file():
        return options._DATA_FOLDER
    if sys.platform == 'win32':
        base = (
            os.environ.get('LOCALAPPDATA')
            or pathlib.Path.home() / 'AppData' / 'Local')
        return pathlib.Path(base) / 'fjc_biographies'
    base = (
        os.environ.get('XDG_DATA_HOME')
        or pathlib.Path.home() / '.local' / 'share')
    return pathlib.Path(base) / 'fjc_biographies'

download(categories=None, folder=None, *, overwrite=False)

Downloads the FJC's files of the directory.

A file that was downloaded before is skipped unless overwrite is True. The FJC adds new judges and corrects its data as it goes, so overwrite the files to get the latest data.

Parameters:

Name	Type	Description	Default
categories	Iterable[str] | str | None	the categories to download ("demographics", "service", "other_service", "education", "career", and "other_nominations"). Defaults to None, in which case every category is downloaded.	None
folder	Path | str | None	the data folder, whose "raw" folder the files are saved in. Defaults to None, in which case data_folder() is used.	None
overwrite	bool	whether to download a file that is already there. Defaults to False.	False

Returns:

Type	Description
dict[str, Path]	The path of each file, by its category.

Raises:

Type	Description
ValueError	if a category is not one of the FJC's.

Examples:

>>> import fjc_biographies
>>> fjc_biographies.download(['service', 'demographics'])

Source code in src/fjc_biographies/downloader.py

def download(
    categories: Iterable[str] | str | None = None,
    folder: pathlib.Path | str | None = None,
    *,
    overwrite: bool = False) -> dict[str, pathlib.Path]:
    """Downloads the FJC's files of the directory.

    A file that was downloaded before is skipped unless `overwrite` is True.
    The FJC adds new judges and corrects its data as it goes, so overwrite
    the files to get the latest data.

    Args:
        categories: the categories to download ("demographics", "service",
            "other_service", "education", "career", and "other_nominations").
            Defaults to None, in which case every category is downloaded.
        folder: the data folder, whose "raw" folder the files are saved in.
            Defaults to None, in which case `data_folder()` is used.
        overwrite: whether to download a file that is already there. Defaults
            to False.

    Returns:
        The path of each file, by its category.

    Raises:
        ValueError: if a category is not one of the FJC's.

    Examples:
        >>> import fjc_biographies
        >>> fjc_biographies.download(['service', 'demographics'])  # doctest: +SKIP

    """
    chosen = _categories(categories)
    raw = raw_folder(folder)
    paths = {}
    for category in chosen:
        path = raw / options._CATEGORIES[category]
        if overwrite or not path.is_file():
            _save(options._FJC_URL + path.name, path)
        else:
            logger.info('Skipped %s, which already exists.', path.name)
        paths[category] = path
    return paths

raw_folder(folder=None)

Returns the folder of the downloaded files.

Parameters:

Name	Type	Description	Default
folder	Path | str | None	the data folder. Defaults to None, in which case data_folder() is used.	None

Returns:

Type	Description
Path	The "raw" folder of the data folder. It is not created.

Source code in src/fjc_biographies/downloader.py

def raw_folder(folder: pathlib.Path | str | None = None) -> pathlib.Path:
    """Returns the folder of the downloaded files.

    Args:
        folder: the data folder. Defaults to None, in which case
            `data_folder()` is used.

    Returns:
        The "raw" folder of the data folder. It is not created.

    """
    root = pathlib.Path(folder).expanduser() if folder else data_folder()
    return root / 'raw'