ae-base 0.3.54__tar.gz → 0.3.55__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ae_base
3
- Version: 0.3.54
3
+ Version: 0.3.55
4
4
  Summary: ae namespace module portion base: basic constants, helper functions and context manager
5
5
  Home-page: https://gitlab.com/ae-group/ae_base
6
6
  Author: AndiEcker
@@ -69,17 +69,17 @@ Dynamic: summary
69
69
 
70
70
  <!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae V0.3.95 -->
71
71
  <!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_namespace_root V0.3.14 -->
72
- # base 0.3.54
72
+ # base 0.3.55
73
73
 
74
74
  [![GitLab develop](https://img.shields.io/gitlab/pipeline/ae-group/ae_base/develop?logo=python)](
75
75
  https://gitlab.com/ae-group/ae_base)
76
76
  [![LatestPyPIrelease](
77
- https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.53?logo=python)](
78
- https://gitlab.com/ae-group/ae_base/-/tree/release0.3.53)
77
+ https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.54?logo=python)](
78
+ https://gitlab.com/ae-group/ae_base/-/tree/release0.3.54)
79
79
  [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
80
80
  https://pypi.org/project/ae-base/#history)
81
81
 
82
- >ae_base module 0.3.54.
82
+ >ae_base module 0.3.55.
83
83
 
84
84
  [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
85
85
  https://ae-group.gitlab.io/ae_base/coverage/index.html)
@@ -1,16 +1,16 @@
1
1
  <!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae V0.3.95 -->
2
2
  <!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_namespace_root V0.3.14 -->
3
- # base 0.3.54
3
+ # base 0.3.55
4
4
 
5
5
  [![GitLab develop](https://img.shields.io/gitlab/pipeline/ae-group/ae_base/develop?logo=python)](
6
6
  https://gitlab.com/ae-group/ae_base)
7
7
  [![LatestPyPIrelease](
8
- https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.53?logo=python)](
9
- https://gitlab.com/ae-group/ae_base/-/tree/release0.3.53)
8
+ https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.54?logo=python)](
9
+ https://gitlab.com/ae-group/ae_base/-/tree/release0.3.54)
10
10
  [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
11
11
  https://pypi.org/project/ae-base/#history)
12
12
 
13
- >ae_base module 0.3.54.
13
+ >ae_base module 0.3.55.
14
14
 
15
15
  [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
16
16
  https://ae-group.gitlab.io/ae_base/coverage/index.html)
@@ -7,7 +7,7 @@ functions, useful classes and context managers.
7
7
 
8
8
  .. note::
9
9
  on import of this module, while running on Android OS, it will monkey patch the :mod:`shutil` module
10
- to allow to use them on Android devices. therefore the import of this module should be one of the first ones
10
+ to allow using them on Android devices. therefore, the import of this module should be one of the first ones
11
11
  in your app's main module.
12
12
 
13
13
 
@@ -18,7 +18,7 @@ ISO format strings for ``date`` and ``datetime`` values are provided by the cons
18
18
  :data:`DATE_TIME_ISO`.
19
19
 
20
20
  the :data:`UNSET` constant is useful in cases where ``None`` is a valid data value and another special value is needed
21
- to specify that e.g. an argument or attribute has no (valid) value or did not get specified/passed.
21
+ to specify that e.g., an argument or attribute has no (valid) value or did not get specified/passed.
22
22
 
23
23
  default values to compile file and folder names for a package or an app project are provided by the constants:
24
24
  :data:`DOCS_FOLDER`, :data:`TESTS_FOLDER`, :data:`TEMPLATES_FOLDER`, :data:`BUILD_CONFIG_FILE`,
@@ -36,7 +36,7 @@ in order to convert and transfer Unicode character outside the 7-bit ASCII range
36
36
  like http, use the helper functions :func:`ascii_str` and :func:`str_ascii`.
37
37
 
38
38
  :func:`now_str` creates a timestamp string with the actual UTC date and time. the :func:`utc_datetime` provides the
39
- actual UTC date and time as datetime object.
39
+ actual UTC date and time as a datetime object.
40
40
 
41
41
  to write more compact and readable code for the most common file I/O operations, the helper functions :func:`read_file`
42
42
  and :func:`write_file` are wrapping Python's built-in :func:`open` function and its context manager.
@@ -44,11 +44,12 @@ and :func:`write_file` are wrapping Python's built-in :func:`open` function and
44
44
  the function :func:`duplicates` returns the duplicates of an iterable type.
45
45
 
46
46
  in order to hide/mask secrets like credit card numbers, passwords or tokens in deeply nested data structures,
47
- before they get dumped e.g. to an app log file, the function :func:`mask_secrets` can be used.
47
+ before they get dumped e.g., to an app log file, the function :func:`mask_secrets` can be used.
48
48
 
49
49
  :func:`norm_line_sep` is converting any combination of line separators of a string to a single new-line character.
50
50
 
51
- :func:`norm_name` converts any string into a name that can be used e.g. as file name or as method/attribute name.
51
+ the function :func:`norm_name` converts any string into a name that can be used e.g., as a file name
52
+ or as a method/attribute name.
52
53
 
53
54
  to normalize a file path, in order to remove `.`, `..` placeholders, to resolve symbolic links or to make it relative or
54
55
  absolute, call the function :func:`norm_path`.
@@ -57,16 +58,16 @@ absolute, call the function :func:`norm_path`.
57
58
  either as a URL slug or as a file name. use the function :func:`dedefuse` to convert this string back to the
58
59
  corresponding URL/URI or file path.
59
60
 
60
- :func:`camel_to_snake` and :func:`snake_to_camel` providing name conversions of class and method names.
61
+ the functions :func:`camel_to_snake` and :func:`snake_to_camel` providing name conversions of class and method names.
61
62
 
62
- to encode Unicode strings to other codecs the functions :func:`force_encoding` and :func:`to_ascii` can be used.
63
+ to encode Unicode strings to other codecs, the functions :func:`force_encoding` and :func:`to_ascii` can be used.
63
64
 
64
- the :func:`round_traditional` function get provided by this module for traditional rounding of float values. the
65
- function signature is fully compatible to Python's :func:`round` function.
65
+ the :func:`round_traditional` function gets provided by this module for traditional rounding of float values. the
66
+ function signature is fully compatible with Python's :func:`round` function.
66
67
 
67
68
  the function :func:`instantiate_config_parser` ensures that the :class:`~configparser.ConfigParser` instance is
68
- correctly configured, e.g. to support case-sensitive config variable names and to use :class:`ExtendedInterpolation` for
69
- the interpolation argument.
69
+ correctly configured, e.g., to support case-sensitive config variable names and to use :class:`ExtendedInterpolation`
70
+ as the interpolation argument.
70
71
 
71
72
  :func:`app_name_guess` guesses the name of o running Python application from the application environment, with the help
72
73
  of :func:`build_config_variable_values`, which determines config-variable-values from the build spec file of an app
@@ -79,29 +80,29 @@ operating system constants and helpers
79
80
  the string :data:`os_platform` provides the OS where your app is running, extending Python's :func:`sys.platform`
80
81
  for mobile platforms like Android and iOS.
81
82
 
82
- :func:`os_host_name`, :func:`os_local_ip` and :func:`os_user_name` are determining machine and user information from
83
- the OS.
83
+ the functions :func:`os_host_name`, :func:`os_local_ip` and :func:`os_user_name` are determining machine and
84
+ user information from the OS.
84
85
 
85
86
  use :func:`env_str` to determine the value of an OS environment variable with automatic variable name conversion. other
86
87
  helper functions provided by this namespace portion to determine the values of the most important system environment
87
88
  variables for your application are :func:`sys_env_dict` and :func:`sys_env_text`.
88
89
 
89
90
  to integrate system environment variables from ``.env`` files into :data:`os.environ` the helper functions
90
- :func:parse_dotenv`, :func:`load_env_var_defaults` and :func:`load_dotenvs` are provided.
91
+ :func:`parse_dotenv`, :func:`load_env_var_defaults` and :func:`load_dotenvs` are provided.
91
92
 
92
93
  the :mod:`ae.core` portion is providing more OS-specific constants and helper functions, like e.g.
93
94
  :func:`start_app_service` and :func:`request_app_permissions`.
94
95
 
95
96
  .. note::
96
- on import of this module, while running on Android OS, it will monkey patch the :mod:`shutil` module to allow to
97
- use them on Android devices, and on first app start request the permissions of your app. therefore to prevent
98
- permission errors, the import of this module should be the first statement in the main module of your app.
97
+ on import of this module, while running on Android OS, it will monkey patch the :mod:`shutil` module to allow
98
+ using them on Android devices, and on the first app start requesting the permissions of your app. therefore, to
99
+ prevent permission errors, the import of this module should be the first statement in the main module of your app.
99
100
 
100
101
 
101
102
  types, classes and mixins
102
103
  -------------------------
103
104
 
104
- the :class:`UnsetType` class can be used e.g. for the declaration of optional function and method parameters,
105
+ the :class:`UnsetType` class can be used e.g., for the declaration of optional function and method parameters,
105
106
  allowing also ``None`` is an accepted argument value.
106
107
 
107
108
  to extend any class with an intelligent error message handling, add the mixin :class:`ErrorMsgMixin` to it.
@@ -113,7 +114,7 @@ enclosed in curly brackets. the function :func:`format_given` is using them to f
113
114
  generic context manager
114
115
  -----------------------
115
116
 
116
- the context manager :func:`in_wd` allows to switch the current working directory temporarily. the following
117
+ the context manager :func:`in_wd` allows switching the current working directory temporarily. the following
117
118
  example demonstrates a typical usage, together with a temporary path, created with the help of Pythons
118
119
  :class:`~tempfile.TemporaryDirectory` class::
119
120
 
@@ -129,7 +130,7 @@ call stack inspection
129
130
  :func:`module_attr` dynamically determines a reference to an attribute (variable, function, class, ...) in a module.
130
131
 
131
132
  :func:`module_name`, :func:`stack_frames`, :func:`stack_var` and :func:`stack_vars` are inspecting the call stack frames
132
- to determine e.g. variable values of the callers of a function/method.
133
+ to determine e.g., variable values of the callers of a function/method.
133
134
 
134
135
  .. hint::
135
136
  the :class:`AppBase` class uses these helper functions to determine the :attr:`version <AppBase.app_version>` and
@@ -167,7 +168,7 @@ from types import ModuleType
167
168
  from typing import Any, Callable, Generator, Iterable, Optional, Union, cast
168
169
 
169
170
 
170
- __version__ = '0.3.54'
171
+ __version__ = '0.3.55'
171
172
 
172
173
 
173
174
  os_path_abspath = os.path.abspath
@@ -190,7 +191,7 @@ TEMPLATES_FOLDER = 'templates'
190
191
  """ template folder name, used in template and namespace root projects to maintain and provide common file templates """
191
192
 
192
193
  BUILD_CONFIG_FILE = 'buildozer.spec' #: gui app build config file
193
- PACKAGE_INCLUDE_FILES_PREFIX = 'ae_' #: file/folder names prefix included into setup package_data/ae_updater
194
+ PACKAGE_INCLUDE_FILES_PREFIX = 'ae_' #: file/folder names prefix included in setup package_data/ae_updater
194
195
 
195
196
  PY_CACHE_FOLDER = '__pycache__' #: python cache folder name
196
197
  PY_EXT = '.py' #: file extension for modules and hooks
@@ -239,14 +240,15 @@ NAME_PARTS_SEP = '_' #: name parts separator char
239
240
 
240
241
  NOW_STR_FORMAT = "{sep}%Y%m%d{sep}%H%M%S{sep}%f" #: timestamp format of :func:`now_str`
241
242
 
242
- SKIPPED_MODULES = ('ae.base', 'ae.paths', 'ae.dynamicod', 'ae.core', 'ae.console', 'ae.gui_app', 'ae.gui_help',
243
+ SKIPPED_MODULES = ('ae.base', 'ae.paths', 'ae.dynamicod', 'ae.core', 'ae.console',
244
+ 'ae.gui', 'ae.gui.app', 'ae.gui.tours', 'ae.gui.utils',
243
245
  'ae.kivy', 'ae.kivy.apps', 'ae.kivy.behaviors', 'ae.kivy.i18n', 'ae.kivy.tours', 'ae.kivy.widgets',
244
246
  'ae.enaml_app', 'ae.beeware_app', 'ae.pyglet_app', 'ae.pygobject_app', 'ae.dabo_app',
245
247
  'ae.qpython_app', 'ae.appjar_app', 'importlib._bootstrap', 'importlib._bootstrap_external')
246
248
  """ skipped modules used as default by :func:`module_name`, :func:`stack_var` and :func:`stack_vars` """
247
249
 
248
250
 
249
- # using only object() does not provide proper representation string
251
+ # using only object() does not provide a proper representation string
250
252
  class UnsetType:
251
253
  """ (singleton) UNSET (type) object class. """
252
254
  def __bool__(self):
@@ -280,7 +282,7 @@ def app_name_guess() -> str:
280
282
 
281
283
 
282
284
  def ascii_str(unicode_str: str) -> str:
283
- """ convert non-ASCII chars in str object to a revertible 7-bit/ASCII representation, e.g. to put in a http header.
285
+ """ convert non-ASCII chars to a revertible 7-bit/ASCII representation, e.g., to put in an http header.
284
286
 
285
287
  :param unicode_str: string to encode/convert.
286
288
  :return: revertible representation of the specified string, using only ASCII characters.
@@ -315,7 +317,7 @@ def build_config_variable_values(*names_defaults: tuple[str, Any], section: str
315
317
 
316
318
 
317
319
  def camel_to_snake(name: str) -> str:
318
- """ convert name from CamelCase to snake_case.
320
+ """ convert a name from CamelCase to snake_case.
319
321
 
320
322
  :param name: name string in CamelCaseFormat.
321
323
  :return: name in snake_case_format.
@@ -330,9 +332,9 @@ def camel_to_snake(name: str) -> str:
330
332
 
331
333
 
332
334
  def deep_dict_update(data: dict, update: dict):
333
- """ update the optionally nested data dict in-place with the items and sub-items from the update dict.
335
+ """ update the optionally nested data dict in-place with the items and subitems from the update dict.
334
336
 
335
- :param data: dict to be updated/extended. non-existing keys of dict-sub-items will be added.
337
+ :param data: dict to be updated/extended. non-existing keys of dict-subitems will be added.
336
338
  :param update: dict with the [sub-]items to update in the :paramref:`~deep_dict_update.data` dict.
337
339
 
338
340
  .. hint:: the module/portion :mod:`ae.deep` is providing more deep update helper functions.
@@ -349,8 +351,8 @@ def deep_dict_update(data: dict, update: dict):
349
351
 
350
352
  URI_SEP_CHAR = '⫻' # U+2AFB: TRIPLE SOLIDUS BINARY RELATION
351
353
  ASCII_UNICODE = (
352
- ('/', '⁄'), # U+2044: Fraction Slash; '∕' U+2215: Division Slash; '⧸' U+29F8: Big Solidus
353
- # ; '╱' U+FF0F: Fullwidth Solidus; '╱' U+2571: Box Drawings Light Diagonal Upper Right to Lower Left
354
+ ('/', '⁄'), # U+2044: Fraction Slash; '∕' U+2215: Division Slash; '⧸' U+29F8: Big Solidus;
355
+ # '╱' U+FF0F: Fullwidth Solidus; '╱' U+2571: Box Drawings Light Diagonal Upper Right to Lower Left
354
356
  ('|', '।'), # U+0964: Devanagari Danda
355
357
  ('\\', '﹨'), # U+FE68: SMALL REVERSE SOLIDUS; '⑊' U+244A OCR DOUBLE BACKSLASH; '⧵' U+29F5 REV. SOLIDUS OPERATOR
356
358
  (':', '﹕'), # U+FE55: Small Colon
@@ -384,7 +386,7 @@ ASCII_UNICODE = (
384
386
  # ' ' U+202F: Narrow No-Break Space (NNBSP); ' ' U+205F Medium Mathematical Space;
385
387
  # '␠' U+2420 symbol for space; '␣' U+2423 Open Box; ' ' U+3000: Ideographic Space
386
388
  (chr(127), '␡'), # U+2421: DELETE SYMBOL
387
- # ('_', '𛲖'), # U+1BC96: Duployan Affix Low Line; '_' U+FF3F Fullwidth Low Line
389
+ # ('_', '𛲖'), # U+1BC96: Duployan Affix Low Line; '_' U+FF3F Fullwidth Low Line
388
390
  )
389
391
  """ transformation table of special ASCII to Unicode alternative character,
390
392
  see https://www.compart.com/en/unicode/category/Po and https://xahlee.info/comp/unicode_naming_slash.html (http!) """
@@ -420,7 +422,7 @@ def defuse(value: str) -> str:
420
422
 
421
423
  in most unix variants only the slash and the ASCII 0 characters are not allowed in file names.
422
424
 
423
- in MS Windows are not allowed: ASCII 0..31 / | \\ : * ? ” % < > ( ). some blogs recommend to also not allow
425
+ in MS Windows are not allowed: ASCII 0..31 / | \\ : * ? ” % < > ( ). some blogs recommend also not allowing
424
426
  (convert) the characters # and '.
425
427
 
426
428
  only old POSIX seems to be even more restricted (only allowing alphanumeric characters plus . - and _).
@@ -506,7 +508,7 @@ class UnformattedValue: # pylint: disable=too-few-public-met
506
508
  self.key = key
507
509
 
508
510
  def __format__(self, format_spec: str):
509
- """ overriding Python object class method to return placeholder unchanged including the curly brackets. """
511
+ """ overriding Python object class method to return placeholder unchanged, including the curly brackets. """
510
512
  # pylint: disable=consider-using-f-string
511
513
  return "{{{}{}}}".format(self.key, ":" + format_spec if format_spec else "")
512
514
 
@@ -525,14 +527,12 @@ def format_given(text: str, placeholder_map: dict[str, Any], strict: bool = Fals
525
527
  """ replacement for Python's str.format_map(), keeping intact placeholders that are not in the specified mapping.
526
528
 
527
529
  :param text: text/template in which the given/specified placeholders will get replaced. in contrary
528
- to str.format_map() no KeyError will be raised for placeholders not specified in
530
+ to :func:`str.format_map`, no KeyError will be raised for placeholders not specified in
529
531
  :paramref:`~format_given.placeholder_map`.
530
532
  :param placeholder_map: dict with placeholder keys to be replaced in :paramref:`~format_given.text` argument.
531
- :param strict: pass True to raise error for text templates containing unpaired curly brackets.
533
+ :param strict: pass True to raise an error for text templates containing unpaired curly brackets.
532
534
  :return: the specified :paramref:`~format_given.text` with only the placeholders specified in
533
535
  :paramref:`~format_given.placeholder_map` replaced with their respective map value.
534
- additionally any ValueError that would be thrown by str.format_map(), e.g. if the
535
-
536
536
 
537
537
  inspired by the answer of CodeManX in `https://stackoverflow.com/questions/3536303`__
538
538
  """
@@ -546,7 +546,7 @@ def format_given(text: str, placeholder_map: dict[str, Any], strict: bool = Fals
546
546
 
547
547
 
548
548
  def full_stack_trace(ex: Exception) -> str:
549
- """ get full stack trace from an exception.
549
+ """ get a full stack trace from an exception.
550
550
 
551
551
  :param ex: exception instance.
552
552
  :return: str with stack trace info.
@@ -577,7 +577,7 @@ def import_module(import_name: str, path: Optional[Union[str, UnsetType]] = UNSE
577
577
  :param path: optional file path of the module to import. if this arg is not specified or has the
578
578
  default value (:data:`UNSET`), then the path will be determined from the import name.
579
579
  specify ``None`` to prevent the module search.
580
- :return: a reference to the loaded module or ``None`` if module could not be imported.
580
+ :return: a reference to the loaded module or ``None`` if the module could not be imported.
581
581
  """
582
582
  if path is UNSET:
583
583
  path = import_name.replace('.', os_path_sep)
@@ -602,23 +602,23 @@ def instantiate_config_parser() -> ConfigParser:
602
602
  cfg_parser = ConfigParser(allow_no_value=True, interpolation=ExtendedInterpolation())
603
603
  # set optionxform to have case-sensitive var names (or use 'lambda option: option')
604
604
  # mypy V 0.740 bug - see mypy issue #5062: adding pragma "type: ignore" breaks PyCharm (showing
605
- # .. inspection warning "Non-self attribute could not be type-hinted"), but
606
- # .. also cast(Callable[[Arg(str, 'option')], str], str) and # type: ... is not working
607
- # .. (because Arg is not available in plain mypy, only in the extra mypy_extensions package)
605
+ # inspection warning "Non-self attribute could not be type-hinted"), but
606
+ # also cast(Callable[[Arg(str, 'option')], str], str) and # type: ... is not working
607
+ # (because Arg is not available in plain mypy, only in the extra mypy_extensions package)
608
608
  setattr(cfg_parser, 'optionxform', str)
609
609
  return cfg_parser
610
610
 
611
611
 
612
612
  @contextmanager
613
613
  def in_wd(new_cwd: str) -> Generator[None, None, None]:
614
- """ context manager to temporary switch the current working directory / cwd.
614
+ """ context manager to temporarily switch the current working directory / cwd.
615
615
 
616
616
  :param new_cwd: path to the directory to switch to (within the context/with block).
617
617
  an empty string gets interpreted as the current working directory.
618
618
  """
619
619
  cur_dir = os.getcwd()
620
620
  try:
621
- if new_cwd: # empty new_cwd results in current working folder (no dir change needed/prevent error)
621
+ if new_cwd: # empty new_cwd results in the current working folder (no dir change needed/prevent error)
622
622
  os.chdir(new_cwd)
623
623
  yield
624
624
  finally:
@@ -628,7 +628,7 @@ def in_wd(new_cwd: str) -> Generator[None, None, None]:
628
628
  def load_dotenvs():
629
629
  """ detect and load multiple ``.env`` files in/above the current working directory and the calling module folder.
630
630
 
631
- .. hint:: call from main module of project/app in order to also load ``.env`` files in/above the project folder.
631
+ .. hint:: call from the main module of project/app in order to also load ``.env`` files in/above the project folder.
632
632
  """
633
633
  load_env_var_defaults(os.getcwd())
634
634
  if file_name := stack_var('__file__'):
@@ -636,17 +636,18 @@ def load_dotenvs():
636
636
 
637
637
 
638
638
  def load_env_var_defaults(start_dir: str):
639
- """ detect and load chain of ``.env`` files starting in the specified folder or one above.
639
+ """ detect and load a chain of ``.env`` files starting in the specified folder or one above.
640
640
 
641
- :param start_dir: folder to start search of an ``.env`` file, if not found then checks the parent folder.
642
- if a first ``.env`` file got found, then load their console/shell environment variables
643
- into Python's :data:`os.environ`. after loading the first one, repeat to check for
641
+ :param start_dir: folder to start search of an ``.env`` file, if not found, then checks the parent folder.
642
+ if the first ``.env `` file got found, then load their shell environment variables
643
+ into Python's :data:`os.environ`. after loading the first one, it repeats to check for
644
644
  further ``.env`` files in the parent folder to load them too, until either detecting
645
645
  a folder without an ``.env`` file or until an ``.env`` got loaded from the root folder.
646
646
 
647
647
  .. note::
648
648
  only variables that are not declared in :data:`os.environ` will be added (with the
649
- value specified in the ``.env`` file to be loaded).
649
+ value specified in the ``.env`` file to be loaded). the variable values declared in the subfolders
650
+ are having preference over the values declared in the parent folders.
650
651
  """
651
652
  file_path = os_path_abspath(os_path_join(start_dir, DOTENV_FILE_NAME))
652
653
  if not os_path_isfile(file_path):
@@ -684,7 +685,7 @@ def mask_secrets(data: Union[dict, Iterable], fragments: Iterable[str] = ('passw
684
685
  :param data: iterable deep data structure wherein its item values get masked if their related dict
685
686
  item key contains one of the fragments specified in :paramref:`~mask_secrets.fragments`.
686
687
  :param fragments: dict key string fragments of which the related value will be masked. each fragment has
687
- to be specified in lower case! defaults to ('password', 'pwd') if not passed.
688
+ to be specified with lower case chars! defaults to ('password', 'pwd') if not passed.
688
689
  :return: specified data structure with the secrets masked (¡in-place!).
689
690
  """
690
691
  is_dict = isinstance(data, dict)
@@ -708,8 +709,8 @@ def module_attr(import_name: str, attr_name: str = "") -> Optional[Any]:
708
709
  :param attr_name: name of the attribute declared within the module. do not specify or pass an empty
709
710
  string to get/return a reference to the imported module instance.
710
711
  :return: module instance or module attribute value
711
- or None if module not found
712
- or UNSET if module attribute doesn't exist.
712
+ or None if the module got not found
713
+ or UNSET if the module attribute doesn't exist.
713
714
 
714
715
  .. note:: a previously not imported module will *not* be added to `sys.modules` by this function.
715
716
 
@@ -722,10 +723,10 @@ def module_file_path(local_object: Optional[Callable] = None) -> str:
722
723
  """ determine the absolute path of the module from which this function got called.
723
724
 
724
725
  :param local_object: optional local module, class, method, function, traceback, frame, or code object of the
725
- calling module (passing `lambda: 0` also works). omit to use instead the `__file__`
726
- module variable (which will not work if the module is frozen by ``py2exe`` or
727
- ``PyInstaller``).
728
- :return: module path (inclusive module file name) or empty string if path not found/determinable.
726
+ calling module (passing `lambda: 0` also works). omit this argument in order to use
727
+ the `__file__` module variable (which will not work if the module is frozen by
728
+ ``py2exe`` or ``PyInstaller``).
729
+ :return: module path (inclusive module file name) or empty string if not found/determinable.
729
730
  """
730
731
  if local_object:
731
732
  file_path = getsourcefile(local_object)
@@ -746,11 +747,11 @@ def module_name(*skip_modules: str, depth: int = 0) -> Optional[str]:
746
747
  """ find the first module in the call stack that is *not* in :paramref:`~module_name.skip_modules`.
747
748
 
748
749
  :param skip_modules: module names to skip (def=this and other core modules, see :data:`SKIPPED_MODULES`).
749
- :param depth: the calling level from which on to search. the default value 0 refers the frame and
750
+ :param depth: the calling level from which on to search. the default value 0 refers to the frame and
750
751
  the module of the caller of this function.
751
752
  pass 1 or an even higher value if you want to get the module name of a function/method
752
753
  in a deeper level in the call stack.
753
- :return: the module name of the call stack level specified by :paramref:`~module_name.depth`.
754
+ :return: the module name of the call stack level, specified by :paramref:`~module_name.depth`.
754
755
  """
755
756
  if not skip_modules:
756
757
  skip_modules = SKIPPED_MODULES
@@ -771,7 +772,7 @@ def norm_name(name: str, allow_num_prefix: bool = False) -> str:
771
772
 
772
773
  :param name: any string to be converted into a valid variable/method/file/... name.
773
774
  :param allow_num_prefix: pass True to allow leading digits in the returned normalized name.
774
- :return: cleaned/normalized/converted name string (e.g. for a variable-/method-/file-name).
775
+ :return: cleaned/normalized/converted name string (e.g., for a variable-/method-/file-name).
775
776
  """
776
777
  str_parts: list[str] = []
777
778
  for char in name:
@@ -784,10 +785,10 @@ def norm_name(name: str, allow_num_prefix: bool = False) -> str:
784
785
 
785
786
  def norm_path(path: str, make_absolute: bool = True, remove_base_path: str = "", remove_dots: bool = True,
786
787
  resolve_sym_links: bool = True) -> str:
787
- """ normalize path, replacing `..`/`.` parts or the tilde character (for home folder) and transform to relative/abs.
788
+ """ normalize a path, replacing `..`/`.` parts or the tilde character (home folder) and transform to relative/abs.
788
789
 
789
790
  :param path: path string to normalize/transform.
790
- :param make_absolute: pass False to not convert path to an absolute path.
791
+ :param make_absolute: pass False to not convert the returned path to an absolute path.
791
792
  :param remove_base_path: pass a valid base path to return a relative path, even if the argument values of
792
793
  :paramref:`~norm_path.make_absolute` or :paramref:`~norm_path.resolve_sym_links` are
793
794
  `True`.
@@ -797,8 +798,8 @@ def norm_path(path: str, make_absolute: bool = True, remove_base_path: str = "",
797
798
  :return: normalized path string: absolute if :paramref:`~norm_path.remove_base_path` is empty and
798
799
  either :paramref:`~norm_path.make_absolute` or :paramref:`~norm_path.resolve_sym_links`
799
800
  is `True`; relative if :paramref:`~norm_path.remove_base_path` is a base path of
800
- :paramref:`~norm_path.path` or if :paramref:`~norm_path.path` got specified as relative
801
- path and neither :paramref:`~norm_path.make_absolute` nor
801
+ :paramref:`~norm_path.path` or if :paramref:`~norm_path.path` got specified as a
802
+ relative path and neither :paramref:`~norm_path.make_absolute` nor
802
803
  :paramref:`~norm_path.resolve_sym_links` is `True`.
803
804
 
804
805
  .. hint:: the :func:`~ae.paths.normalize` function additionally replaces :data:`~ae.paths.PATH_PLACEHOLDERS`.
@@ -852,6 +853,7 @@ def os_local_ip() -> str:
852
853
  or empty string if this machine is not connected to any network.
853
854
  """
854
855
  socket1 = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
856
+ ip_address = ""
855
857
  try:
856
858
  socket1.connect(('10.255.255.255', 1)) # doesn't even have to be reachable
857
859
  ip_address = socket1.getsockname()[0]
@@ -863,7 +865,7 @@ def os_local_ip() -> str:
863
865
  socket2.connect(('<broadcast>', 0))
864
866
  ip_address = socket2.getsockname()[0]
865
867
  except (OSError, IOError, Exception): # pylint: disable=broad-except
866
- ip_address = ""
868
+ pass
867
869
  finally:
868
870
  socket2.close()
869
871
  finally:
@@ -946,13 +948,13 @@ def parse_dotenv(file_path: str) -> dict[str, str]:
946
948
 
947
949
 
948
950
  def project_main_file(import_name: str, project_path: str = "") -> str:
949
- """ determine the main module file path of a project package, containing the project __version__ module variable.
951
+ """ determine the main module file path of a project package containing the project __version__ module variable.
950
952
 
951
- :param import_name: import name of the module/package (including namespace prefixes for namespace packages).
953
+ :param import_name: name of the module/package (including namespace prefixes, separated with dots).
952
954
  :param project_path: optional path where the project of the package/module is situated. not needed if the
953
955
  current working directory is the root folder of either the import_name project or of a
954
956
  sister project (under the same project parent folder).
955
- :return: absolute file path/name of main module or empty string if no main/version file found.
957
+ :return: absolute file path of the main module or empty string if no main/version file is found.
956
958
  """
957
959
  *namespace_dirs, portion_name = import_name.split('.')
958
960
  project_name = ('_'.join(namespace_dirs) + '_' if namespace_dirs else "") + portion_name
@@ -970,6 +972,7 @@ def project_main_file(import_name: str, project_path: str = "") -> str:
970
972
  for path_parts in paths_parts:
971
973
  main_file = os_path_join(module_path, *path_parts)
972
974
  if os_path_isfile(main_file):
975
+ # noinspection PyTypeChecker
973
976
  return main_file
974
977
  return ""
975
978
 
@@ -978,22 +981,22 @@ def read_file(file_path: str, extra_mode: str = "", encoding: Optional[str] = No
978
981
  ) -> Union[str, bytes]:
979
982
  """ returning content of the text/binary file specified by file_path argument as string.
980
983
 
981
- :param file_path: file path/name to load into a string or a bytes array.
982
- :param extra_mode: extra open mode flag characters appended to "r" onto open() mode argument. pass "b" to
983
- read the content of a binary file returned as bytes array. in binary mode the argument
984
- passed in :paramref:`~read_file.error_handling` will be ignored.
984
+ :param file_path: path/name of the file to load the content from.
985
+ :param extra_mode: extra open mode flag characters appended to "r" onto the :func:`open` mode argument.
986
+ pass "b" to read the content of a binary file returned of the type `bytes`. in binary
987
+ mode the argument passed in :paramref:`~read_file.error_handling` will be ignored.
985
988
  :param encoding: encoding used to load and convert/interpret the file content.
986
- :param error_handling: for files opened in text mode pass `'strict'` or ``None`` to return ``None`` (instead of
987
- an empty string) for the cases where either a decoding `ValueError` exception or any
989
+ :param error_handling: for files opened in text mode, pass `'strict'` or ``None`` to return ``None`` (instead
990
+ of an empty string) for the cases where either a decoding `ValueError` exception or any
988
991
  `OSError`, `FileNotFoundError` or `PermissionError` exception got raised.
989
992
  the default value `'ignore'` will ignore any decoding errors (missing some characters)
990
993
  and will return an empty string on any file/os exception. this parameter will be ignored
991
994
  if the :paramref:`~read_file.extra_mode` argument contains the 'b' character (to read
992
995
  the file content as binary/bytes-array).
993
996
  :return: file content string or bytes array.
994
- :raises FileNotFoundError: if file does not exist.
997
+ :raises FileNotFoundError: if the file to read from does not exist.
995
998
  :raises OSError: if :paramref:`~read_file.file_path` is misspelled or contains invalid characters.
996
- :raises PermissionError: if current OS user account lacks permissions to read the file content.
999
+ :raises PermissionError: if the current OS user account lacks permissions to read the file content.
997
1000
  :raises ValueError: on decoding errors.
998
1001
  """
999
1002
  extra_kwargs = {} if "b" in extra_mode else {'errors': error_handling}
@@ -1004,7 +1007,7 @@ def read_file(file_path: str, extra_mode: str = "", encoding: Optional[str] = No
1004
1007
  def round_traditional(num_value: float, num_digits: int = 0) -> float:
1005
1008
  """ round numeric value traditional.
1006
1009
 
1007
- needed because python round() is working differently, e.g. round(0.075, 2) == 0.07 instead of 0.08
1010
+ needed because python round() is working differently, e.g., round(0.075, 2) == 0.07 instead of 0.08
1008
1011
  inspired by https://stackoverflow.com/questions/31818050/python-2-7-round-number-to-nearest-integer.
1009
1012
 
1010
1013
  :param num_value: float value to be round.
@@ -1035,7 +1038,7 @@ def stack_frames(depth: int = 1) -> Generator: # Generator[frame, None, None]
1035
1038
  """ generator returning the call stack frame from the level given in :paramref:`~stack_frames.depth`.
1036
1039
 
1037
1040
  :param depth: the stack level to start; the first returned frame by this generator. the default value
1038
- (1) refers the next deeper stack frame, respectively the one of the caller of this
1041
+ (1) refers to the next deeper stack frame, respectively the one of the caller of this
1039
1042
  function. pass 2 or a higher value if you want to start with an even deeper frame/level.
1040
1043
  :return: generated frames of the call stack.
1041
1044
  """
@@ -1056,7 +1059,7 @@ def stack_var(name: str, *skip_modules: str, scope: str = '', depth: int = 1) ->
1056
1059
  :param scope: pass 'locals' to only check for local variables (ignoring globals) or
1057
1060
  'globals' to only check for global variables (ignoring locals). the default value (an
1058
1061
  empty string) will not restrict the scope, returning either a local or global value.
1059
- :param depth: the calling level from which on to search. the default value (1) refers the next
1062
+ :param depth: the calling level from which on to search. the default value (1) refers to the next
1060
1063
  deeper stack frame, which is the caller of the function. pass 2 or an even higher
1061
1064
  value if you want to start the variable search from a deeper level in the call stack.
1062
1065
  :return: the variable value of a deeper level within the call stack or UNSET if the variable was
@@ -1073,19 +1076,19 @@ def stack_vars(*skip_modules: str,
1073
1076
  """ determine all global and local variables in a calling stack/frames.
1074
1077
 
1075
1078
  :param skip_modules: module names to skip (def=see :data:`SKIPPED_MODULES` module constant).
1076
- :param find_name: if passed then the returned stack frame must contain a variable with the passed name.
1079
+ :param find_name: if passed, then the returned stack frame must contain a variable with the passed name.
1077
1080
  :param scope: scope to search the variable name passed via :paramref:`~stack_vars.find_name`. pass
1078
1081
  'locals' to only search for local variables (ignoring globals) or 'globals' to only
1079
1082
  check for global variables (ignoring locals). passing an empty string will find the
1080
- variable within either locals and globals.
1083
+ variable within either locals or globals.
1081
1084
  :param min_depth: the call stack level from which on to search. the default value (1) refers the next
1082
- deeper stack frame, respectively to the caller of this function. pass 2 or a higher
1085
+ deeper stack frame, respectively, to the caller of this function. pass 2 or a higher
1083
1086
  value if you want to get the variables from a deeper level in the call stack.
1084
1087
  :param max_depth: the maximum depth in the call stack from which to return the variables. if the specified
1085
- argument is not zero and no :paramref:`~stack_vars.skip_modules` are specified then the
1088
+ argument is not zero and no :paramref:`~stack_vars.skip_modules` are specified, then the
1086
1089
  first deeper stack frame that is not within the default :data:`SKIPPED_MODULES` will be
1087
- returned. if this argument and :paramref:`~stack_vars.find_name` get not passed then the
1088
- variables of the top stack frame will be returned.
1090
+ returned. if this argument and :paramref:`~stack_vars.find_name` get not passed,
1091
+ then the variables of the top stack frame will be returned.
1089
1092
  :return: tuple of the global and local variable dicts and the depth in the call stack.
1090
1093
  """
1091
1094
  if not skip_modules:
@@ -1102,8 +1105,8 @@ def stack_vars(*skip_modules: str,
1102
1105
  break
1103
1106
  if max_depth and depth > max_depth:
1104
1107
  break
1105
- # experienced strange overwrites of locals (e.g. self) when returning f_locals directly (adding .copy() fixed it)
1106
- # check if f_locals is a dict (because enaml is using their DynamicScope object which is missing a copy method)
1108
+ # experienced strange overwrites of locals (e.g., self) when returning f_locals directly (adding .copy() fixed it)
1109
+ # check if f_locals is a dict (because enaml is using their DynamicScope object, which is missing a copy method)
1107
1110
  if isinstance(loc, dict):
1108
1111
  loc = loc.copy()
1109
1112
  return glo.copy(), loc, depth - 1
@@ -1139,7 +1142,7 @@ def sys_env_dict() -> dict[str, Any]:
1139
1142
 
1140
1143
  def sys_env_text(ind_ch: str = " ", ind_len: int = 12, key_ch: str = "=", key_len: int = 15,
1141
1144
  extra_sys_env_dict: Optional[dict[str, str]] = None) -> str:
1142
- """ compile formatted text block with system environment info.
1145
+ """ compile a formatted text block with system environment info.
1143
1146
 
1144
1147
  :param ind_ch: indent character (defaults to " ").
1145
1148
  :param ind_len: indent depths (default=12 characters).
@@ -1185,24 +1188,24 @@ def write_file(file_path: str, content: Union[str, bytes],
1185
1188
  """ (over)write the file specified by :paramref:`~write_file.file_path` with text or binary/bytes content.
1186
1189
 
1187
1190
  :param file_path: file path/name to write the passed content into (overwriting any previous content!).
1188
- :param content: new file content passed either as string or bytes array. if a bytes array get passed
1191
+ :param content: new file content passed either as string or as `bytes`. if a byte array gets passed,
1189
1192
  then this method will automatically write the content as binary.
1190
1193
  :param extra_mode: additional open mode flag characters. passed to the `mode` argument of :func:`open` if
1191
1194
  this argument starts with 'a' or 'w', else this argument value will be appended to 'w'
1192
- before it get passed to the `mode` argument of :func:`open`.
1193
- if the :paramref:`~write_file.content` is a bytes array, then a 'b' character will
1195
+ before it gets passed to the `mode` argument of :func:`open`.
1196
+ if the :paramref:`~write_file.content` is of the `bytes` type, then a 'b' character will
1194
1197
  be automatically added to the `mode` argument of :func:`open` (if not already specified
1195
1198
  in this argument).
1196
1199
  :param encoding: encoding used to write/convert/interpret the file content to write.
1197
1200
  :param make_dirs: pass True to automatically create not existing folders specified in
1198
1201
  :paramref:`~write_file.file_path`.
1199
- :raises FileExistsError: if file exists already and is write-protected.
1202
+ :raises FileExistsError: if the file to write to exists already and is write-protected.
1200
1203
  :raises FileNotFoundError: if parts of the file path do not exist.
1201
1204
  :raises OSError: if :paramref:`~write_file.file_path` is misspelled or contains invalid characters.
1202
- :raises PermissionError: if current OS user account lacks permissions to read the file content.
1205
+ :raises PermissionError: if the current OS user account lacks permissions to read the file content.
1203
1206
  :raises ValueError: on decoding errors.
1204
1207
 
1205
- to extend this function for Android 14+ see `<https://github.com/beeware/toga/pull/1158#issuecomment-2254564657>`__
1208
+ to extend this function for Android 14+, see `<https://github.com/beeware/toga/pull/1158#issuecomment-2254564657>`__
1206
1209
  and `<https://gist.github.com/neonankiti/05922cf0a44108a2e2732671ed9ef386>`__
1207
1210
  Yes, to use ACTION_CREATE_DOCUMENT, you don't supply a URI in the intent. You wait for the intent result, and that
1208
1211
  will contain a URI which you can write to.
@@ -1307,7 +1310,7 @@ if os_platform == 'android': # pragma: no
1307
1310
  except Exception: # pylint: disable=broad-except
1308
1311
  pass
1309
1312
 
1310
- # monkey patch the :func:`shutil.copystat` and :func:`shutil.copymode` helper functions, which are crashing on
1313
+ # monkey patches the :func:`shutil.copystat` and :func:`shutil.copymode` helper functions, which are crashing on
1311
1314
  # 'android' (see # `<https://bugs.python.org/issue28141>`__ and `<https://bugs.python.org/issue32073>`__). these
1312
1315
  # functions are used by shutil.copy2/copy/copytree/move to copy OS-specific file attributes.
1313
1316
  # although shutil.copytree() and shutil.move() are copying/moving the files correctly when the copy_function
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ae_base
3
- Version: 0.3.54
3
+ Version: 0.3.55
4
4
  Summary: ae namespace module portion base: basic constants, helper functions and context manager
5
5
  Home-page: https://gitlab.com/ae-group/ae_base
6
6
  Author: AndiEcker
@@ -69,17 +69,17 @@ Dynamic: summary
69
69
 
70
70
  <!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae V0.3.95 -->
71
71
  <!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_namespace_root V0.3.14 -->
72
- # base 0.3.54
72
+ # base 0.3.55
73
73
 
74
74
  [![GitLab develop](https://img.shields.io/gitlab/pipeline/ae-group/ae_base/develop?logo=python)](
75
75
  https://gitlab.com/ae-group/ae_base)
76
76
  [![LatestPyPIrelease](
77
- https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.53?logo=python)](
78
- https://gitlab.com/ae-group/ae_base/-/tree/release0.3.53)
77
+ https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.54?logo=python)](
78
+ https://gitlab.com/ae-group/ae_base/-/tree/release0.3.54)
79
79
  [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
80
80
  https://pypi.org/project/ae-base/#history)
81
81
 
82
- >ae_base module 0.3.54.
82
+ >ae_base module 0.3.55.
83
83
 
84
84
  [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
85
85
  https://ae-group.gitlab.io/ae_base/coverage/index.html)
File without changes
File without changes
File without changes
File without changes