From eada747a220503be91a160deeebfa05064d71a9e Mon Sep 17 00:00:00 2001 From: James B Date: Wed, 11 Dec 2024 16:15:03 +0000 Subject: [PATCH 1/2] docs: Add a page to docs for all functions meant to be called externally https://github.com/OpenDataServices/lib-cove-2/issues/10 --- docs/python-api/fields_present.rst | 11 +++++++ docs/python-api/index.rst | 5 ++- .../schema_dict_fields_generator.rst | 10 ++++++ libcove2/common.py | 31 ++++++++++++------- 4 files changed, 42 insertions(+), 15 deletions(-) create mode 100644 docs/python-api/fields_present.rst create mode 100644 docs/python-api/schema_dict_fields_generator.rst diff --git a/docs/python-api/fields_present.rst b/docs/python-api/fields_present.rst new file mode 100644 index 0000000..419e458 --- /dev/null +++ b/docs/python-api/fields_present.rst @@ -0,0 +1,11 @@ +Fields Present (get_fields_present_with_examples & fields_present_generator) +============================================================================ + + +.. autofunction:: libcove2.common.get_fields_present_with_examples + + +.. autofunction:: libcove2.common.fields_present_generator + + + diff --git a/docs/python-api/index.rst b/docs/python-api/index.rst index 4c6b46c..0e22664 100644 --- a/docs/python-api/index.rst +++ b/docs/python-api/index.rst @@ -11,6 +11,5 @@ It does not document Python that is not intended for reuse by others (you can re org-ids.rst additional_fields.rst - -TODO schema_dict_fields_generator - + schema_dict_fields_generator.rst + fields_present.rst diff --git a/docs/python-api/schema_dict_fields_generator.rst b/docs/python-api/schema_dict_fields_generator.rst new file mode 100644 index 0000000..a7687ed --- /dev/null +++ b/docs/python-api/schema_dict_fields_generator.rst @@ -0,0 +1,10 @@ +schema_dict_fields_generator +============================ + + + +.. autofunction:: libcove2.common.schema_dict_fields_generator + + + + diff --git a/libcove2/common.py b/libcove2/common.py index 0214d68..a1f3fcc 100644 --- a/libcove2/common.py +++ b/libcove2/common.py @@ -54,18 +54,20 @@ def schema_dict_fields_generator(schema_dict, registry=None, defs=None): """ Iterate over fields in the input schema (with recursion): - Parameters: - schema_dict (dict): Current input schema or subset thereof. - registry (int, optional): Registry object from referencing package. - See https://referencing.readthedocs.io/ for details. - Contains all schema files that might be referenced. - Currently only urn: references are supported. - defs (dict, optional): Contents of "$defs" schema property. - This will usually only be used internally when function is - calling itself. - - Yields: - str: Contains path of field + Parameters: + + * schema_dict (dict): Current input schema or subset thereof. + * registry (int, optional): Registry object from referencing package. + See https://referencing.readthedocs.io/ for details. + Contains all schema files that might be referenced. + Currently only urn: references are supported. + * defs (dict, optional): Contents of "$defs" schema property. + This will usually only be used internally when function is + calling itself. + + Yields: + + * str: Contains path of field """ if "$defs" in schema_dict: defs = schema_dict["$defs"] @@ -141,6 +143,8 @@ def schema_dict_fields_generator(schema_dict, registry=None, defs=None): def get_additional_fields_info(json_data, schema_fields, fields_regex=False): + """Returns information on any additional fields that are + in the passed data but which are NOT defined in the schema.""" fields_present = get_fields_present_with_examples(json_data) additional_fields = {} @@ -172,6 +176,8 @@ def get_additional_fields_info(json_data, schema_fields, fields_regex=False): def get_fields_present_with_examples(*args, **kwargs): + """Returns list of fields present in some data, + with a count of how many times they exist and some examples of their values.""" counter = {} for key, value in fields_present_generator(*args, **kwargs): if key not in counter: @@ -186,6 +192,7 @@ def get_fields_present_with_examples(*args, **kwargs): def fields_present_generator(json_data, prefix=""): + """Returns list of fields present in some data.""" if isinstance(json_data, dict): for key, value in json_data.items(): new_key = f"{prefix}/{key}" From 82e10f059d4bb19b2f0013ec4b041f073ede8aa8 Mon Sep 17 00:00:00 2001 From: James B Date: Wed, 11 Dec 2024 16:19:18 +0000 Subject: [PATCH 2/2] `org_id_file_fresh` renamed to private function `_org_id_file_fresh` It is not intended to be used externally. https://github.com/OpenDataServices/lib-cove-2/issues/10 --- CHANGELOG.md | 2 ++ libcove2/common.py | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c69aa7a..1815587 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Changed - Improved handling of jsonschema: Handle urn references and allOf conditional in schema_dict_fields_generator +- `org_id_file_fresh` renamed to private function `_org_id_file_fresh` - it is not intended to be used externally + ## [0.1.0] - 2023-05-31 diff --git a/libcove2/common.py b/libcove2/common.py index a1f3fcc..a03eb64 100644 --- a/libcove2/common.py +++ b/libcove2/common.py @@ -205,7 +205,7 @@ def fields_present_generator(json_data, prefix=""): yield from fields_present_generator(item, prefix) -def org_id_file_fresh(org_id_file_contents, check_date): +def _org_id_file_fresh(org_id_file_contents, check_date): """Unless the file was downloaded on greater than or equal to 'check_date' it is considered stale.""" org_id_file_date_downloaded_date = datetime.datetime.strptime( @@ -232,7 +232,7 @@ def get_orgids_prefixes(orgids_url=None): except FileNotFoundError: pass - if org_id_file_contents is None or not org_id_file_fresh( + if org_id_file_contents is None or not _org_id_file_fresh( org_id_file_contents, today ): # Refresh the file