Skip to content

Commit

Permalink
Adjust documentation of exposed API
Browse files Browse the repository at this point in the history
I stumbled across this being a potential point of confusion in the
Exifread mapping repository's PR 21.

References:
* casework/CASE-Implementation-PyPI-Exifread#21

Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>
  • Loading branch information
ajnelson-nist committed May 12, 2023
1 parent 0cfe6d1 commit 4ac8d4c
Showing 1 changed file with 9 additions and 3 deletions.
12 changes: 9 additions & 3 deletions case_utils/local_uuid.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,14 @@

"""
This library is a wrapper for uuid, provided to generate repeatable UUIDs if requested.
The function local_uuid() should be used in code where a user could be expected to opt in to non-random UUIDs.
"""

__version__ = "0.3.2"

__all__ = ["configure", "local_uuid"]

import logging
import os
import pathlib
Expand All @@ -34,13 +38,13 @@

def configure() -> None:
"""
This function is part of setting up demo_uuid() to generate non-random UUIDs. See demo_uuid() documentation for further setup notes.
This function is part of setting up _demo_uuid() to generate non-random UUIDs. See _demo_uuid() documentation for further setup notes.
"""
global DEMO_UUID_BASE

if os.getenv("DEMO_UUID_REQUESTING_NONRANDOM") == "NONRANDOM_REQUESTED":
warnings.warn(
"Environment variable DEMO_UUID_REQUESTING_NONRANDOM is deprecated. See case_utils.local_uuid.demo_uuid for usage notes on its replacement, CASE_DEMO_NONRANDOM_UUID_BASE. Proceeding with random UUIDs.",
"Environment variable DEMO_UUID_REQUESTING_NONRANDOM is deprecated. See case_utils.local_uuid._demo_uuid for usage notes on its replacement, CASE_DEMO_NONRANDOM_UUID_BASE. Proceeding with random UUIDs.",
FutureWarning,
)
return
Expand Down Expand Up @@ -109,10 +113,12 @@ def configure() -> None:
DEMO_UUID_BASE = "/".join(demo_uuid_base_parts)


def demo_uuid() -> str:
def _demo_uuid() -> str:
"""
This function generates a repeatable UUID, drawing on non-varying elements of the environment and process call for entropy.
This function is not intended to be called outside of this module. Instead, local_uuid() should be called.
WARNING: This function was developed for use ONLY for reducing (but not eliminating) version-control edits to identifiers when generating sample data. It creates UUIDs that are decidedly NOT random, and should remain consistent on repeated calls to the importing script.
To prevent accidental non-random UUID usage, two setup steps need to be done before calling this function:
Expand Down

0 comments on commit 4ac8d4c

Please sign in to comment.