Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adjust documentation of exposed local_uuid API #115

Merged
merged 1 commit into from
Aug 24, 2023
Merged

Adjust documentation of exposed local_uuid API #115

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions case_utils/local_uuid.py
View file
Open in desktop
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 Expand Up @@ -148,4 +154,4 @@ def local_uuid() -> str:
if DEMO_UUID_BASE is None:
return str(uuid.uuid4())
else:
return demo_uuid()
return _demo_uuid()