basstler-core 4.2.0__tar.gz → 4.2.2__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.
Files changed (44) hide show
  1. {basstler_core-4.2.0 → basstler_core-4.2.2}/PKG-INFO +1 -1
  2. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/exceptions.py +27 -0
  3. basstler_core-4.2.2/src/basstler/module.py +98 -0
  4. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/package_map.py +23 -0
  5. basstler_core-4.2.2/tests/test_module.py +144 -0
  6. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_package_map.py +38 -1
  7. {basstler_core-4.2.0 → basstler_core-4.2.2}/.gitignore +0 -0
  8. {basstler_core-4.2.0 → basstler_core-4.2.2}/LICENSE +0 -0
  9. {basstler_core-4.2.0 → basstler_core-4.2.2}/NOTICE +0 -0
  10. {basstler_core-4.2.0 → basstler_core-4.2.2}/pyproject.toml +0 -0
  11. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/bash.py +0 -0
  12. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/class_name.py +0 -0
  13. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/class_property.py +0 -0
  14. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/command_line.py +0 -0
  15. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/credential_origin.py +0 -0
  16. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/directory_tree.py +0 -0
  17. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/email_address.py +0 -0
  18. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/environment.py +0 -0
  19. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/exit_codes.py +0 -0
  20. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/json_model.py +0 -0
  21. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/locations.py +0 -0
  22. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/package_layout.py +0 -0
  23. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/plugin_root.py +0 -0
  24. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/render_common.py +0 -0
  25. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/shell_configuration.py +0 -0
  26. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/standard_streams.py +0 -0
  27. {basstler_core-4.2.0 → basstler_core-4.2.2}/src/basstler/text_file.py +0 -0
  28. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/__init__.py +0 -0
  29. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/command_failures.py +0 -0
  30. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/conftest.py +0 -0
  31. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_bash.py +0 -0
  32. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_class_name.py +0 -0
  33. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_class_property.py +0 -0
  34. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_command_line.py +0 -0
  35. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_directory_tree.py +0 -0
  36. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_email_address.py +0 -0
  37. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_environment.py +0 -0
  38. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_exit_codes.py +0 -0
  39. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_locations.py +0 -0
  40. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_plugin_root.py +0 -0
  41. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_render_common.py +0 -0
  42. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_shell_configuration.py +0 -0
  43. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_standard_streams.py +0 -0
  44. {basstler_core-4.2.0 → basstler_core-4.2.2}/tests/test_text_file.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: basstler-core
3
- Version: 4.2.0
3
+ Version: 4.2.2
4
4
  Summary: The foundation every basstler distribution builds on: locations, environment variables, exceptions and the package map.
5
5
  Project-URL: Source, https://github.com/KAOS-repositories/basstler
6
6
  Project-URL: Bug Tracker, https://github.com/KAOS-repositories/basstler/issues
@@ -11,11 +11,15 @@ from abc import ABC, abstractmethod
11
11
  from dataclasses import dataclass
12
12
  from enum import StrEnum
13
13
  from pathlib import Path, PurePosixPath
14
+ from typing import TYPE_CHECKING
14
15
 
15
16
  from basstler.class_property import classproperty
16
17
  from basstler.exit_codes import CommandFailure, StackExitCode
17
18
  from basstler.locations import BasstlerVariable, ClaudeCodeVariable, PluginLocation
18
19
 
20
+ if TYPE_CHECKING:
21
+ from basstler.module import Module
22
+
19
23
 
20
24
  class DataclassException(Exception, ABC):
21
25
  """
@@ -221,6 +225,29 @@ class MalformedEmailAddressError(DataclassException, ValueError):
221
225
  return "give the address your commits should carry, e.g. you@example.com"
222
226
 
223
227
 
228
+ @dataclass
229
+ class ModuleOutsideRootError(DataclassException, ValueError):
230
+ """
231
+ Raised when a module is named relative to a root that does not hold it.
232
+ """
233
+
234
+ module: Module
235
+ """
236
+ The module that was named relative to :attr:`root`.
237
+ """
238
+
239
+ root: Module
240
+ """
241
+ The package or module that does not hold :attr:`module`.
242
+ """
243
+
244
+ def error_message(self) -> str:
245
+ return f"{self.module.absolute} is not within {self.root.absolute}"
246
+
247
+ def suggest_correction(self) -> str:
248
+ return f"name a module that starts with {self.root.absolute}"
249
+
250
+
224
251
  @dataclass
225
252
  class BashNotFoundError(DataclassException, FileNotFoundError):
226
253
  """
@@ -0,0 +1,98 @@
1
+ """
2
+ A module of a Python package: its dotted name, and what it is relative to.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+ from pathlib import Path
9
+ from typing import Self
10
+
11
+ from basstler.exceptions import ModuleOutsideRootError
12
+
13
+ SEPARATOR = "."
14
+ """
15
+ What separates the parts of a dotted name, and marks a relative one when it leads.
16
+ """
17
+
18
+
19
+ @dataclass(frozen=True, order=True)
20
+ class Module:
21
+ """
22
+ A module, a package or a subpackage, named by its dotted name, in its absolute form
23
+ or relative to a root.
24
+ """
25
+
26
+ parts: tuple[str, ...]
27
+ """
28
+ The names between the dots, outermost package first, below :attr:`root` when there
29
+ is one.
30
+ """
31
+
32
+ root: Module | None = None
33
+ """
34
+ The package :attr:`parts` lie below; none for an absolute module.
35
+ """
36
+
37
+ @classmethod
38
+ def from_dotted_name(cls, dotted_name: str, root: Module | None = None) -> Self:
39
+ """
40
+ :param dotted_name: A module's name without a leading dot; empty for the module
41
+ without parts.
42
+ :param root: The package the name lies below; none for an absolute name.
43
+ :return: The module it names.
44
+ """
45
+ return cls(tuple(dotted_name.split(SEPARATOR)) if dotted_name else (), root)
46
+
47
+ def __str__(self) -> str:
48
+ return f"{SEPARATOR if self.root else ''}{self.dotted_name}"
49
+
50
+ @property
51
+ def dotted_name(self) -> str:
52
+ """
53
+ The parts joined by dots, without the leading dot of a relative module.
54
+ """
55
+ return SEPARATOR.join(self.parts)
56
+
57
+ @property
58
+ def absolute(self) -> Module:
59
+ """
60
+ This module with its root's parts in front; itself when it has no root.
61
+ """
62
+ if self.root is None:
63
+ return self
64
+ return Module((*self.root.absolute.parts, *self.parts))
65
+
66
+ @property
67
+ def path(self) -> Path:
68
+ """
69
+ The parts as directories, below the root's directory and without a suffix.
70
+ """
71
+ return Path(*self.parts)
72
+
73
+ @property
74
+ def top_level_package(self) -> Self:
75
+ """
76
+ The outermost package holding the module, which is the first part of its
77
+ absolute form.
78
+ """
79
+ return type(self)(self.absolute.parts[:1])
80
+
81
+ def is_within(self, root: Module) -> bool:
82
+ """
83
+ :param root: A package, or any module.
84
+ :return: Whether this module is *root* or lies under it, comparing whole parts.
85
+ """
86
+ return self.absolute.parts[: len(root.absolute.parts)] == root.absolute.parts
87
+
88
+ def relative_to(self, root: Module) -> Self:
89
+ """
90
+ :param root: A package, or any module, that holds this module.
91
+ :return: This module's name below *root*, which it keeps as its root.
92
+ :raises ModuleOutsideRootError: When this module is not within *root*.
93
+ """
94
+ if not self.is_within(root):
95
+ raise ModuleOutsideRootError(self, root)
96
+ return type(self)(
97
+ self.absolute.parts[len(root.absolute.parts) :], root.absolute
98
+ )
@@ -199,6 +199,12 @@ class DistributionDeclaration:
199
199
  The distributions it may import.
200
200
  """
201
201
 
202
+ libraries: tuple[str, ...] = ()
203
+ """
204
+ The names, as its ``pyproject.toml`` spells them, of the third-party libraries it
205
+ requires itself.
206
+ """
207
+
202
208
  @classmethod
203
209
  def read(cls, directory: Path) -> DistributionDeclaration:
204
210
  """
@@ -230,6 +236,7 @@ class DistributionDeclaration:
230
236
  for name in metadata.requirement_names
231
237
  if name in names
232
238
  ),
239
+ tuple(name for name in metadata.requirement_names if name not in names),
233
240
  )
234
241
 
235
242
  def claim_length(self, module: str) -> int:
@@ -315,6 +322,22 @@ class PackageMap(Mapping[Distribution, DistributionDeclaration]):
315
322
  graph.add_edge(nodes[declaration.distribution], nodes[dependency], None)
316
323
  return graph
317
324
 
325
+ def libraries_required_by_distribution(
326
+ self, distribution: Distribution
327
+ ) -> frozenset[str]:
328
+ """
329
+ :param distribution: A declared distribution.
330
+ :return: The third-party libraries it requires itself, and those of every
331
+ distribution it lists, as their ``pyproject.toml`` files spell them.
332
+ """
333
+ declaration = self[distribution]
334
+ return frozenset(declaration.libraries).union(
335
+ *(
336
+ self.libraries_required_by_distribution(dependency)
337
+ for dependency in declaration.dependencies
338
+ )
339
+ )
340
+
318
341
  def claiming(self, module: str) -> DistributionDeclaration | None:
319
342
  """
320
343
  :param module: A module's dotted name within ``basstler``.
@@ -0,0 +1,144 @@
1
+ """
2
+ Tests for :mod:`basstler.module`: a module as a dotted name that is, or is not, relative
3
+ to a root.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from pathlib import Path
9
+
10
+ import pytest
11
+
12
+ from basstler.exceptions import ModuleOutsideRootError
13
+ from basstler.module import Module
14
+
15
+ # %% reading and writing the dotted name
16
+
17
+
18
+ def test_a_module_reads_its_dotted_name():
19
+ """
20
+ The parts of ``low.helpers`` are ``low`` and ``helpers``.
21
+ """
22
+ assert Module.from_dotted_name("low.helpers") == Module(("low", "helpers"))
23
+
24
+
25
+ def test_a_module_is_written_as_its_dotted_name():
26
+ """
27
+ Writing a module back gives the name it was read from.
28
+ """
29
+ assert str(Module(("low", "helpers"))) == "low.helpers"
30
+
31
+
32
+ def test_the_empty_dotted_name_is_the_module_without_parts():
33
+ """
34
+ A ``from .
35
+
36
+ import x`` style statement with no module names the empty module.
37
+ """
38
+ assert Module.from_dotted_name("") == Module(())
39
+
40
+
41
+ # %% top-level package
42
+
43
+
44
+ def test_the_top_level_package_is_the_first_part():
45
+ """
46
+ ``pydantic.fields`` belongs to the package ``pydantic``.
47
+ """
48
+ assert Module.from_dotted_name("pydantic.fields").top_level_package == Module(
49
+ ("pydantic",)
50
+ )
51
+
52
+
53
+ # %% relative to a root
54
+
55
+
56
+ @pytest.mark.parametrize(
57
+ ("module", "root", "is_within"),
58
+ [
59
+ ("basstler.low.helpers", "basstler", True),
60
+ ("basstler.low", "basstler.low", True),
61
+ ("basstler.low", "basstler.high", False),
62
+ ("basstler_extra.low", "basstler", False),
63
+ ("pydantic", "basstler", False),
64
+ ],
65
+ )
66
+ def test_a_module_is_within_a_root_when_the_root_is_a_prefix_of_its_parts(
67
+ module, root, is_within
68
+ ):
69
+ """
70
+ Only whole parts count: ``basstler_extra`` is not within ``basstler``.
71
+ """
72
+ assert (
73
+ Module.from_dotted_name(module).is_within(Module.from_dotted_name(root))
74
+ is is_within
75
+ )
76
+
77
+
78
+ def test_a_module_relative_to_a_root_keeps_the_root():
79
+ """
80
+ ``basstler.low.helpers`` relative to ``basstler`` is ``low.helpers`` below
81
+ ``basstler``, so it does not lose where it lies.
82
+ """
83
+ root = Module(("basstler",))
84
+ module = Module.from_dotted_name("basstler.low.helpers")
85
+
86
+ assert module.relative_to(root) == Module(("low", "helpers"), root)
87
+
88
+
89
+ def test_a_relative_module_is_written_with_a_leading_dot():
90
+ """
91
+ The leading dot marks the form as relative, as in a relative import.
92
+ """
93
+ module = Module(("low", "helpers"), Module(("basstler",)))
94
+
95
+ assert str(module) == ".low.helpers"
96
+
97
+
98
+ def test_a_relative_module_has_an_absolute_form_with_its_root():
99
+ """
100
+ Joining the root's parts back gives ``basstler.low.helpers``.
101
+ """
102
+ module = Module(("low", "helpers"), Module(("basstler",)))
103
+
104
+ assert module.absolute == Module(("basstler", "low", "helpers"))
105
+
106
+
107
+ def test_an_absolute_module_is_its_own_absolute_form():
108
+ """
109
+ A module with no root needs no joining.
110
+ """
111
+ module = Module(("basstler", "low"))
112
+
113
+ assert module.absolute == module
114
+
115
+
116
+ def test_a_relative_module_is_within_the_root_it_lies_below():
117
+ """
118
+ ``.low`` below ``basstler`` is within ``basstler``, though its own parts are not.
119
+ """
120
+ root = Module(("basstler",))
121
+
122
+ assert Module(("low",), root).is_within(root)
123
+
124
+
125
+ def test_the_path_form_of_a_module_is_its_parts_as_directories():
126
+ """
127
+ ``low.helpers`` is the path ``low/helpers`` below its root, without a suffix.
128
+ """
129
+ module = Module(("low", "helpers"), Module(("basstler",)))
130
+
131
+ assert module.path == Path("low", "helpers")
132
+
133
+
134
+ def test_a_module_outside_the_root_is_refused():
135
+ """
136
+ A module that does not start with the root has no name relative to it.
137
+ """
138
+ root = Module(("basstler",))
139
+ module = Module(("pydantic", "fields"))
140
+
141
+ with pytest.raises(ModuleOutsideRootError) as error:
142
+ module.relative_to(root)
143
+
144
+ assert (error.value.module, error.value.root) == (module, root)
@@ -22,7 +22,10 @@ from basstler.package_map import (
22
22
  Workspace,
23
23
  )
24
24
 
25
- from basstler_testing.constants.paths import PackageBoundarySnippet
25
+ from basstler_testing.constants.paths import (
26
+ PackageBoundarySnippet,
27
+ ThirdPartyImportSnippet,
28
+ )
26
29
 
27
30
  # %% the workspace's map
28
31
 
@@ -64,6 +67,40 @@ def test_a_distribution_ships_its_part_and_lists_what_its_metadata_requires():
64
67
  )
65
68
 
66
69
 
70
+ # %% required libraries
71
+
72
+
73
+ @pytest.fixture
74
+ def library_package_map() -> PackageMap:
75
+ """
76
+ :return: The map of the dataset's workspace, whose lower distribution requires
77
+ ``pydantic``.
78
+ """
79
+ return Workspace(ThirdPartyImportSnippet.DIRECTORY.value).package_map
80
+
81
+
82
+ def test_a_distribution_lists_the_libraries_its_metadata_requires(library_package_map):
83
+ """
84
+ The lower distribution lists ``pydantic``, whose version constraint is not part of
85
+ the name; the higher one lists no library of its own.
86
+ """
87
+ assert {
88
+ declaration.distribution: declaration.libraries
89
+ for declaration in library_package_map.declarations
90
+ } == {Distribution.CORE: ("pydantic",), Distribution.GIT: ()}
91
+
92
+
93
+ def test_a_distribution_requires_the_libraries_of_the_distributions_it_lists(
94
+ library_package_map,
95
+ ):
96
+ """
97
+ The higher distribution lists no library, yet needs the lower one's.
98
+ """
99
+ assert library_package_map.libraries_required_by_distribution(Distribution.GIT) == {
100
+ "pydantic"
101
+ }
102
+
103
+
67
104
  # %% looking up a declaration
68
105
 
69
106
 
File without changes
File without changes
File without changes