|
15 | 15 | # We would appreciate acknowledgement if the software is used. |
16 | 16 |
|
17 | 17 | """ |
18 | | -This library is a wrapper for uuid, provided to generate repeatable UUIDs if requested. |
19 | | -
|
20 | | -The function local_uuid() should be used in code where a user could be expected to opt in to non-random UUIDs. |
| 18 | +This library was a wrapper for uuid, provided to generate repeatable UUIDs if requested. It is now a temporary re-export of functionality migrated to cdo_local_uuid. |
21 | 19 | """ |
22 | 20 |
|
23 | | -__version__ = "0.4.1" |
| 21 | +__version__ = "0.5.0" |
24 | 22 |
|
25 | 23 | __all__ = ["configure", "local_uuid"] |
26 | 24 |
|
27 | | -import logging |
28 | | -import os |
29 | | -import pathlib |
30 | | -import sys |
31 | | -import typing |
32 | | -import uuid |
33 | 25 | import warnings |
34 | 26 |
|
35 | | -DEMO_UUID_BASE: typing.Optional[str] = None |
36 | | - |
37 | | -DEMO_UUID_COUNTER: int = 0 |
38 | | - |
39 | | -_logger = logging.getLogger(pathlib.Path(__file__).name) |
40 | | - |
41 | | - |
42 | | -def _is_relative_to(p1: pathlib.Path, p2: pathlib.Path) -> bool: |
43 | | - """ |
44 | | - This function provides pathlib.is_relative_to to Pythons before 3.9. After the End of Life of Python 3.8, this function can be removed. |
45 | | - """ |
46 | | - if sys.version_info < (3, 9): |
47 | | - try: |
48 | | - _ = p1.relative_to(p2) |
49 | | - return True |
50 | | - except ValueError: |
51 | | - return False |
52 | | - else: |
53 | | - return p1.is_relative_to(p2) |
54 | | - |
55 | | - |
56 | | -def configure() -> None: |
57 | | - """ |
58 | | - This function is part of setting up _demo_uuid() to generate non-random UUIDs. See _demo_uuid() documentation for further setup notes. |
59 | | - """ |
60 | | - global DEMO_UUID_BASE |
61 | | - |
62 | | - # _logger.debug("sys.argv = %r.", sys.argv) |
63 | | - |
64 | | - if os.getenv("DEMO_UUID_REQUESTING_NONRANDOM") == "NONRANDOM_REQUESTED": |
65 | | - warnings.warn( |
66 | | - "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.", |
67 | | - FutureWarning, |
68 | | - ) |
69 | | - return |
70 | | - |
71 | | - env_base_dir_name = os.getenv("CASE_DEMO_NONRANDOM_UUID_BASE") |
72 | | - if env_base_dir_name is None: |
73 | | - return |
74 | | - |
75 | | - base_dir_original_path = pathlib.Path(env_base_dir_name) |
76 | | - if not base_dir_original_path.exists(): |
77 | | - warnings.warn( |
78 | | - "Environment variable CASE_DEMO_NONRANDOM_UUID_BASE is expected to refer to an existing directory. Proceeding with random UUIDs.", |
79 | | - RuntimeWarning, |
80 | | - ) |
81 | | - return |
82 | | - if not base_dir_original_path.is_dir(): |
83 | | - warnings.warn( |
84 | | - "Environment variable CASE_DEMO_NONRANDOM_UUID_BASE is expected to refer to a directory. Proceeding with random UUIDs.", |
85 | | - RuntimeWarning, |
86 | | - ) |
87 | | - return |
88 | | - |
89 | | - # Component: An emphasis this is an example. |
90 | | - demo_uuid_base_parts = ["example.org"] |
91 | | - |
92 | | - # Component: Present working directory, relative to CASE_DEMO_NONRANDOM_UUID_BASE if that environment variable is an ancestor of pwd. |
93 | | - base_dir_resolved_path = base_dir_original_path.resolve() |
94 | | - srcdir_original_path = pathlib.Path(os.getcwd()) |
95 | | - srcdir_resolved_path = srcdir_original_path.resolve() |
96 | | - # _logger.debug("base_dir_resolved_path = %r.", base_dir_resolved_path) |
97 | | - # _logger.debug("srcdir_resolved_path = %r.", srcdir_resolved_path) |
98 | | - try: |
99 | | - srcdir_relative_path = srcdir_resolved_path.relative_to(base_dir_resolved_path) |
100 | | - # _logger.debug("srcdir_relative_path = %r.", srcdir_relative_path) |
101 | | - demo_uuid_base_parts.append(str(srcdir_relative_path)) |
102 | | - except ValueError: |
103 | | - # If base_dir is not an ancestor directory of srcdir, default to srcdir. |
104 | | - # _logger.debug("PWD is not relative to base path.") |
105 | | - demo_uuid_base_parts.append(str(srcdir_resolved_path)) |
106 | | - |
107 | | - # Component: Command of argument vector. |
108 | | - env_venv_name = os.getenv("VIRTUAL_ENV") |
109 | | - if env_venv_name is None: |
110 | | - demo_uuid_base_parts.append(sys.argv[0]) |
111 | | - else: |
112 | | - command_original_path = pathlib.Path(sys.argv[0]) |
113 | | - # _logger.debug("command_original_path = %r.", command_original_path) |
114 | | - command_resolved_path = command_original_path.resolve() |
115 | | - # _logger.debug("command_resolved_path = %r.", command_resolved_path) |
116 | | - |
117 | | - # The command could be a command embedded in a virtual |
118 | | - # environment, or it could be a script external to any virtual |
119 | | - # environment. |
120 | | - venv_original_path = pathlib.Path(env_venv_name) |
121 | | - venv_resolved_path = venv_original_path.resolve() |
122 | | - if _is_relative_to(command_resolved_path, venv_resolved_path): |
123 | | - command_relative_path = command_resolved_path.relative_to( |
124 | | - venv_resolved_path |
125 | | - ) |
126 | | - # _logger.debug("command_relative_path = %r.", command_relative_path) |
127 | | - demo_uuid_base_parts.append(str(command_relative_path)) |
128 | | - else: |
129 | | - demo_uuid_base_parts.append(str(command_original_path)) |
130 | | - |
131 | | - if len(sys.argv) > 1: |
132 | | - # Component: Arguments of argument vector. |
133 | | - demo_uuid_base_parts.extend(sys.argv[1:]) |
134 | | - |
135 | | - # _logger.debug("demo_uuid_base_parts = %r.", demo_uuid_base_parts) |
136 | | - |
137 | | - DEMO_UUID_BASE = "/".join(demo_uuid_base_parts) |
138 | | - |
139 | | - |
140 | | -def _demo_uuid() -> str: |
141 | | - """ |
142 | | - This function generates a repeatable UUID, drawing on non-varying elements of the environment and process call for entropy. |
143 | | -
|
144 | | - This function is not intended to be called outside of this module. Instead, local_uuid() should be called. |
145 | | -
|
146 | | - 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. |
147 | | -
|
148 | | - To prevent accidental non-random UUID usage, two setup steps need to be done before calling this function: |
149 | | -
|
150 | | - * An environment variable, CASE_DEMO_NONRANDOM_UUID_BASE, must be set to a string provided by the caller. The variable's required value is the path to some directory. The variable's recommended value is the equivalent of the Make variable "top_srcdir" - that is, the root directory of the containing Git repository, some parent of the current process's current working directory. |
151 | | - * The configure() function in this module must be called. |
152 | | - """ |
153 | | - global DEMO_UUID_BASE |
154 | | - global DEMO_UUID_COUNTER |
155 | | - |
156 | | - if os.getenv("CASE_DEMO_NONRANDOM_UUID_BASE") is None: |
157 | | - raise ValueError( |
158 | | - "demo_uuid() called without CASE_DEMO_NONRANDOM_UUID_BASE in environment." |
159 | | - ) |
160 | | - |
161 | | - if DEMO_UUID_BASE is None: |
162 | | - raise ValueError("demo_uuid() called with DEMO_UUID_BASE unset.") |
163 | | - |
164 | | - parts = [DEMO_UUID_BASE] |
165 | | - |
166 | | - # Component: Incrementing counter. |
167 | | - DEMO_UUID_COUNTER += 1 |
168 | | - parts.append(str(DEMO_UUID_COUNTER)) |
169 | | - |
170 | | - return str(uuid.uuid5(uuid.NAMESPACE_URL, "/".join(parts))) |
171 | | - |
| 27 | +from cdo_local_uuid import configure, local_uuid |
172 | 28 |
|
173 | | -def local_uuid() -> str: |
174 | | - """ |
175 | | - Generate either a UUID4, or if requested via environment configuration, a non-random demo UUID. |
176 | | - """ |
177 | | - global DEMO_UUID_BASE |
178 | | - if DEMO_UUID_BASE is None: |
179 | | - return str(uuid.uuid4()) |
180 | | - else: |
181 | | - return _demo_uuid() |
| 29 | +warnings.warn( |
| 30 | + "case_utils.local_uuid has exported its functionality to cdo_local_uuid. Imports should be changed to use cdo_local_uuid. case_utils currently re-exports that functionality, but this will cease in a future release.", |
| 31 | + DeprecationWarning, |
| 32 | +) |
0 commit comments