<commit_before>"""A module to provide a way of locating resources within the IATI library.

The `get_*_path[s](name)` functions provide information about where to locate particular types of resources with a provided name.

Warning:
    Many of the constants in this module should be deemed private to the IATI library.

    The location of SSOT content may change. It may also require network access to perform certain tasks.

Todo:
    Determine how to distribute SSOT content - with package, or separately (being downloaded at runtime).

"""
import inspect
import os
import re
import pkg_resources
import iati.version


PACKAGE = __name__
"""The name of the resources package.

Used to locate resources when the package is distributed in certain ways that do not provide a standard filesystem.

"""

BASE_PATH = 'resources'
"""The relative location of the resources folder."""
BASE_PATH_STANDARD = os.path.join(BASE_PATH, 'standard')
"""The relative location of resources related to the IATI Standard."""
BASE_PATH_LIB_DATA = os.path.join(BASE_PATH, 'lib_data')
"""The relative location of resources not related to the IATI Standard."""
PATH_CODELISTS = 'codelists'
"""The location of the folder containing Codelists from the SSOT."""
PATH_SCHEMAS = 'schemas'
"""The location of the folder containing Schemas from the SSOT."""
PATH_RULESETS = 'rulesets'
"""The location of the folder containing Rulesets from the SSOT."""
PATH_VERSION_INDEPENDENT = 'version_independent'
"""The location of the folder containing version-independent content."""

FILE_CODELIST_EXTENSION = '.xml'
"""The expected extension of a file containing a Codelist."""
FILE_DATA_EXTENSION = '.xml'
"""The expected extension of a file containing IATI data."""
FILE_RULESET_EXTENSION = '.json'
"""The expected extension of a file containing a Ruleset."""
FILE_SCHEMA_EXTENSION = '.xsd'
"""The expected extension of a file containing a Schema."""

FILE_CODELIST_MAPPING = 'codelist-mapping'
"""The name of a file containing definitions of how Codelist values map to data."""
FILE_RULESET_SCHEMA_NAME = 'ruleset_schema'
"""The name of a file containing the Ruleset schema."""
FILE_RULESET_STANDARD_NAME = 'standard_ruleset'
"""The name of a file containing the Standard Ruleset."""
FILE_SCHEMA_ACTIVITY_NAME = 'iati-activities-schema'
"""The name of a file containing an Activity Schema."""
FILE_SCHEMA_ORGANISATION_NAME = 'iati-organisations-schema'
"""The name of a file containing an Organisation Schema."""


@iati.version.decimalise_integer
@iati.version.allow_possible_version
def get_codelist_paths(version):
    """Find the paths for all Codelists at the specified version of the Standard.

    Args:
        version (str / int / Decimal / iati.Version): The version of the Standard to return the Codelists for.
            Decimal: Return paths for the specified version of the Standard.
            Integer: Return paths for the latest Decimal version within the given integer.
            Version-independent: Return paths for Non-Embedded Codelists.

    Raises:
        TypeError: When a specified version is of a type that cannot represent an IATI version number.
        ValueError: When a specified version is of the correct type, but cannot represent a version of the IATI Standard.

    Returns:
        list(str): A list of paths to all of the Codelists at the specified version of the Standard.

    Todo:
        Look to provide an argument that allows the returned list to be restricted to only Embedded or only Non-Embedded Codelists.<commit_msg>Update documentation for iati.resources.get_codelist_paths()<commit_after>"""A module to provide a way of locating resources within the IATI library.

The `get_*_path[s](name)` functions provide information about where to locate particular types of resources with a provided name.

Warning:
    Many of the constants in this module should be deemed private to the IATI library.

    The location of SSOT content may change. It may also require network access to perform certain tasks.

Todo:
    Determine how to distribute SSOT content - with package, or separately (being downloaded at runtime).

"""
import inspect
import os
import re
import pkg_resources
import iati.version


PACKAGE = __name__
"""The name of the resources package.

Used to locate resources when the package is distributed in certain ways that do not provide a standard filesystem.

"""

BASE_PATH = 'resources'
"""The relative location of the resources folder."""
BASE_PATH_STANDARD = os.path.join(BASE_PATH, 'standard')
"""The relative location of resources related to the IATI Standard."""
BASE_PATH_LIB_DATA = os.path.join(BASE_PATH, 'lib_data')
"""The relative location of resources not related to the IATI Standard."""
PATH_CODELISTS = 'codelists'
"""The location of the folder containing Codelists from the SSOT."""
PATH_SCHEMAS = 'schemas'
"""The location of the folder containing Schemas from the SSOT."""
PATH_RULESETS = 'rulesets'
"""The location of the folder containing Rulesets from the SSOT."""
PATH_VERSION_INDEPENDENT = 'version_independent'
"""The location of the folder containing version-independent content."""

FILE_CODELIST_EXTENSION = '.xml'
"""The expected extension of a file containing a Codelist."""
FILE_DATA_EXTENSION = '.xml'
"""The expected extension of a file containing IATI data."""
FILE_RULESET_EXTENSION = '.json'
"""The expected extension of a file containing a Ruleset."""
FILE_SCHEMA_EXTENSION = '.xsd'
"""The expected extension of a file containing a Schema."""

FILE_CODELIST_MAPPING = 'codelist-mapping'
"""The name of a file containing definitions of how Codelist values map to data."""
FILE_RULESET_SCHEMA_NAME = 'ruleset_schema'
"""The name of a file containing the Ruleset schema."""
FILE_RULESET_STANDARD_NAME = 'standard_ruleset'
"""The name of a file containing the Standard Ruleset."""
FILE_SCHEMA_ACTIVITY_NAME = 'iati-activities-schema'
"""The name of a file containing an Activity Schema."""
FILE_SCHEMA_ORGANISATION_NAME = 'iati-organisations-schema'
"""The name of a file containing an Organisation Schema."""


@iati.version.decimalise_integer
@iati.version.allow_possible_version
def get_codelist_paths(version):
    """Find the paths for all Codelists at the specified version of the Standard.

    Args:
        version (str / int / Decimal / iati.Version): The version of the Standard to return the Codelists for.
            Decimal: Return paths for the specified version of the Standard. Includes paths for both Embedded and Non-Embedded Codelists.
            Integer: Return paths for the latest Decimal version within the given integer.
            Version-independent: Return an empty list.

    Raises:
        TypeError: When a specified version is of a type that cannot represent an IATI version number.
        ValueError: When a specified version is of the correct type, but cannot represent a version of the IATI Standard.

    Returns:
        list(str): A list of paths to all of the Codelists at the specified version of the Standard.

    Note:
        Requesting version-independent Codelists returns an empty list rather raising a ValueError since it is planned that in the future a list of Non-Embedded Codelists will be returned.

    Todo:
        Return a list of Non-Embedded Codelists when 'version-independent' Codelists are requested.

        Look to provide an argument that allows the returned list to be restricted to only Embedded or only Non-Embedded Codelists (or both!).
{'fraction_non_alphanumeric': 0.07235522268289421, 'fraction_numerical': 0.0, 'mean_word_length': 4.446467589220685, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '869910', 'n_tokens_mistral': 2029, 'n_tokens_neox': 1951, 'n_words': 928}