cs-object 0.1.0__tar.gz → 1.0.0__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 (50) hide show
  1. {cs_object-0.1.0/src/cs_object.egg-info → cs_object-1.0.0}/PKG-INFO +63 -5
  2. {cs_object-0.1.0 → cs_object-1.0.0}/README.md +62 -4
  3. {cs_object-0.1.0 → cs_object-1.0.0}/pyproject.toml +2 -2
  4. {cs_object-0.1.0 → cs_object-1.0.0/src/cs_object.egg-info}/PKG-INFO +63 -5
  5. {cs_object-0.1.0 → cs_object-1.0.0}/src/cs_object.egg-info/SOURCES.txt +14 -1
  6. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/__init__.py +13 -0
  7. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/__main__.py +5 -0
  8. cs_object-1.0.0/src/cso_python/authoring.md +551 -0
  9. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/authoring.py +43 -0
  10. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/bindings.py +103 -13
  11. cs_object-1.0.0/src/cso_python/comparison.py +1632 -0
  12. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/definitions.py +62 -6
  13. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/execution.py +332 -57
  14. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/exporter.py +15 -2
  15. cs_object-1.0.0/src/cso_python/external.py +205 -0
  16. cs_object-1.0.0/src/cso_python/guidance.py +29 -0
  17. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/handles.py +1 -1
  18. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/planner.py +245 -315
  19. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/source.py +116 -6
  20. cs_object-1.0.0/src/cso_python/source_plan.py +617 -0
  21. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_authoring_v2.py +56 -0
  22. cs_object-1.0.0/tests/test_binding_types.py +104 -0
  23. cs_object-1.0.0/tests/test_bindings.py +140 -0
  24. cs_object-1.0.0/tests/test_boolean_call_outputs.py +116 -0
  25. cs_object-1.0.0/tests/test_boolean_tables.py +226 -0
  26. cs_object-1.0.0/tests/test_external_functions.py +717 -0
  27. cs_object-1.0.0/tests/test_guidance.py +43 -0
  28. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_handle_reuse.py +18 -0
  29. cs_object-1.0.0/tests/test_method_table.py +1308 -0
  30. cs_object-1.0.0/tests/test_source_plan.py +174 -0
  31. {cs_object-0.1.0 → cs_object-1.0.0}/LICENSE +0 -0
  32. {cs_object-0.1.0 → cs_object-1.0.0}/NOTICE +0 -0
  33. {cs_object-0.1.0 → cs_object-1.0.0}/setup.cfg +0 -0
  34. {cs_object-0.1.0 → cs_object-1.0.0}/src/cs_object.egg-info/dependency_links.txt +0 -0
  35. {cs_object-0.1.0 → cs_object-1.0.0}/src/cs_object.egg-info/top_level.txt +0 -0
  36. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/annotations.py +0 -0
  37. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/describe.py +0 -0
  38. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/function_calls.py +0 -0
  39. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/glyphs.py +0 -0
  40. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/notation.py +0 -0
  41. {cs_object-0.1.0 → cs_object-1.0.0}/src/cso_python/py.typed +0 -0
  42. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_cli.py +0 -0
  43. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_definitions.py +0 -0
  44. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_describe.py +0 -0
  45. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_execution.py +0 -0
  46. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_exporter.py +0 -0
  47. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_function_calls.py +0 -0
  48. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_notation.py +0 -0
  49. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_notation_preflight.py +0 -0
  50. {cs_object-0.1.0 → cs_object-1.0.0}/tests/test_numeric_declarations.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cs-object
3
- Version: 0.1.0
3
+ Version: 1.0.0
4
4
  Summary: Constrained Python authoring and CalculationSourceObject JSON export
5
5
  Author: Viktar B
6
6
  License: Apache-2.0
@@ -16,9 +16,17 @@ Dynamic: license-file
16
16
  # cs-object
17
17
 
18
18
  Author constrained `.cso.py` calculations with Python 3.11+. Runtime dependencies
19
- are the standard library only. Read [authoring](../../docs/authoring.md) before
20
- writing calculations and use [two-panel](../../examples/two-panel/README.md) for
21
- shared metadata and composed calls.
19
+ are the standard library only. Read the complete language and authoring contract
20
+ from your installed wheel before writing calculations:
21
+
22
+ ```sh
23
+ python -m cso_python authoring
24
+ python -m cso_python authoring --out authoring-contract.md
25
+ ```
26
+
27
+ The export includes the installed `cs-object` version and has no checkout-relative
28
+ links. It includes a complete composed-report recipe with a figure. The owning
29
+ source is [authoring.md](src/cso_python/authoring.md).
22
30
 
23
31
  ## Install and run
24
32
 
@@ -90,6 +98,31 @@ The captured path preflights local source and executes captured UTF-8 bytes.
90
98
  Older single-file exports retain the development exporter. This is trusted local
91
99
  calculation authoring, not isolation for hostile Python.
92
100
 
101
+ ## External adapters
102
+
103
+ `external_function` declares a single-file ordinary Python adapter with ordered
104
+ numeric inputs, named outputs, defaults and a reusable method explanation.
105
+ Generate its typed handle with the usual bindings command and import it from
106
+ `_cso_bindings._external.<declaration_module>`. Static tools capture the adapter
107
+ without importing it or requiring its scientific dependencies.
108
+
109
+ Use the handle inside a top-level generated calculation. It executes once per
110
+ authored call and captures every output, including unused diagnostics. Callers
111
+ select named outputs from the returned handle. External handles alone require
112
+ an active calculation context. Direct Python can also call the ordinary helper.
113
+
114
+ Adapters return native finite Python numbers, or a plain dictionary with exactly
115
+ the declared output keys. Convert library scalars explicitly and raise when the
116
+ algorithm fails. Adapter state is shared within a run and starts fresh in the
117
+ next run; installed dependency state is not a process sandbox. See the
118
+ [canonical examples](../../examples/external-functions/README.md).
119
+
120
+ The Python command-line consumer must explicitly advertise support with
121
+ `--supported-execution-protocol 4` before executing an external calculation.
122
+ The coordinated CSO CLI sends that capability automatically. `export` rejects
123
+ external calculations because standalone CSO cannot retain their call evidence.
124
+ Use full captured execution or prepared HTML/PDF instead.
125
+
93
126
  ## Code and checks
94
127
 
95
128
  [Public helpers](src/cso_python/__init__.py), [capture](src/cso_python/source.py),
@@ -97,7 +130,32 @@ calculation authoring, not isolation for hostile Python.
97
130
  [execution](src/cso_python/execution.py) and [bindings](src/cso_python/bindings.py)
98
131
  implement the pipeline described in [the code map](../../docs/code-map.md).
99
132
 
100
- With the wheel installed, run `python -I tests/run.py` from this package directory.
133
+ With the wheel installed, run `python -m pip install -r tests/requirements.txt`
134
+ and `python -I tests/run.py` from this package directory. The test-only mypy pin
135
+ checks positive and negative consumers of freshly generated bindings, including
136
+ keyword arguments and typed public result keys. Runtime dependencies stay empty.
101
137
  The tests use package-owned synthetic fixtures and temporary bindings; no root
102
138
  examples or Node are required. [Workspace integration](../../tests/integration/README.md)
103
139
  owns actual example, installed cross-package and PDF acceptance.
140
+
141
+
142
+ ## Release checks
143
+
144
+ Ship `src/cso_python/authoring.md` in every wheel and sdist. Update that one source
145
+ when the authoring contract changes. `python -m cso_python authoring` reads it
146
+ from the installed package; no initializer-time copy is maintained.
147
+
148
+ Before releasing, run the Python package tests and the repository's
149
+ `npm run test:initializer` against actual archives and a wheel. The installed
150
+ consumer checks the initializer's exact `requirements.txt` pin against wheel
151
+ metadata, exports the installed guide, checks local Markdown links and executes
152
+ the shipped composed-report recipe. A missing guide or stale exported copy fails
153
+ acceptance. Release CI runs these installed consumers before publication.
154
+
155
+ When upgrading the Python version used by new projects, update
156
+ `create-cs-object/template/requirements.txt` and release a new initializer version.
157
+ The two packages may have different version numbers. The exact dependency pin
158
+ selects the language contract; setup exports that wheel's guide each time it runs.
159
+ Existing projects can retain their pin. After an intentional upgrade, rerun setup
160
+ to refresh the local contract. Do not publish an initializer pin before that Python
161
+ version is available on PyPI.
@@ -1,9 +1,17 @@
1
1
  # cs-object
2
2
 
3
3
  Author constrained `.cso.py` calculations with Python 3.11+. Runtime dependencies
4
- are the standard library only. Read [authoring](../../docs/authoring.md) before
5
- writing calculations and use [two-panel](../../examples/two-panel/README.md) for
6
- shared metadata and composed calls.
4
+ are the standard library only. Read the complete language and authoring contract
5
+ from your installed wheel before writing calculations:
6
+
7
+ ```sh
8
+ python -m cso_python authoring
9
+ python -m cso_python authoring --out authoring-contract.md
10
+ ```
11
+
12
+ The export includes the installed `cs-object` version and has no checkout-relative
13
+ links. It includes a complete composed-report recipe with a figure. The owning
14
+ source is [authoring.md](src/cso_python/authoring.md).
7
15
 
8
16
  ## Install and run
9
17
 
@@ -75,6 +83,31 @@ The captured path preflights local source and executes captured UTF-8 bytes.
75
83
  Older single-file exports retain the development exporter. This is trusted local
76
84
  calculation authoring, not isolation for hostile Python.
77
85
 
86
+ ## External adapters
87
+
88
+ `external_function` declares a single-file ordinary Python adapter with ordered
89
+ numeric inputs, named outputs, defaults and a reusable method explanation.
90
+ Generate its typed handle with the usual bindings command and import it from
91
+ `_cso_bindings._external.<declaration_module>`. Static tools capture the adapter
92
+ without importing it or requiring its scientific dependencies.
93
+
94
+ Use the handle inside a top-level generated calculation. It executes once per
95
+ authored call and captures every output, including unused diagnostics. Callers
96
+ select named outputs from the returned handle. External handles alone require
97
+ an active calculation context. Direct Python can also call the ordinary helper.
98
+
99
+ Adapters return native finite Python numbers, or a plain dictionary with exactly
100
+ the declared output keys. Convert library scalars explicitly and raise when the
101
+ algorithm fails. Adapter state is shared within a run and starts fresh in the
102
+ next run; installed dependency state is not a process sandbox. See the
103
+ [canonical examples](../../examples/external-functions/README.md).
104
+
105
+ The Python command-line consumer must explicitly advertise support with
106
+ `--supported-execution-protocol 4` before executing an external calculation.
107
+ The coordinated CSO CLI sends that capability automatically. `export` rejects
108
+ external calculations because standalone CSO cannot retain their call evidence.
109
+ Use full captured execution or prepared HTML/PDF instead.
110
+
78
111
  ## Code and checks
79
112
 
80
113
  [Public helpers](src/cso_python/__init__.py), [capture](src/cso_python/source.py),
@@ -82,7 +115,32 @@ calculation authoring, not isolation for hostile Python.
82
115
  [execution](src/cso_python/execution.py) and [bindings](src/cso_python/bindings.py)
83
116
  implement the pipeline described in [the code map](../../docs/code-map.md).
84
117
 
85
- With the wheel installed, run `python -I tests/run.py` from this package directory.
118
+ With the wheel installed, run `python -m pip install -r tests/requirements.txt`
119
+ and `python -I tests/run.py` from this package directory. The test-only mypy pin
120
+ checks positive and negative consumers of freshly generated bindings, including
121
+ keyword arguments and typed public result keys. Runtime dependencies stay empty.
86
122
  The tests use package-owned synthetic fixtures and temporary bindings; no root
87
123
  examples or Node are required. [Workspace integration](../../tests/integration/README.md)
88
124
  owns actual example, installed cross-package and PDF acceptance.
125
+
126
+
127
+ ## Release checks
128
+
129
+ Ship `src/cso_python/authoring.md` in every wheel and sdist. Update that one source
130
+ when the authoring contract changes. `python -m cso_python authoring` reads it
131
+ from the installed package; no initializer-time copy is maintained.
132
+
133
+ Before releasing, run the Python package tests and the repository's
134
+ `npm run test:initializer` against actual archives and a wheel. The installed
135
+ consumer checks the initializer's exact `requirements.txt` pin against wheel
136
+ metadata, exports the installed guide, checks local Markdown links and executes
137
+ the shipped composed-report recipe. A missing guide or stale exported copy fails
138
+ acceptance. Release CI runs these installed consumers before publication.
139
+
140
+ When upgrading the Python version used by new projects, update
141
+ `create-cs-object/template/requirements.txt` and release a new initializer version.
142
+ The two packages may have different version numbers. The exact dependency pin
143
+ selects the language contract; setup exports that wheel's guide each time it runs.
144
+ Existing projects can retain their pin. After an intentional upgrade, rerun setup
145
+ to refresh the local contract. Do not publish an initializer pin before that Python
146
+ version is available on PyPI.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "cs-object"
7
- version = "0.1.0"
7
+ version = "1.0.0"
8
8
  description = "Constrained Python authoring and CalculationSourceObject JSON export"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -25,4 +25,4 @@ where = ["src"]
25
25
  include = ["cso_python*"]
26
26
 
27
27
  [tool.setuptools.package-data]
28
- cso_python = ["py.typed"]
28
+ cso_python = ["py.typed", "authoring.md"]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cs-object
3
- Version: 0.1.0
3
+ Version: 1.0.0
4
4
  Summary: Constrained Python authoring and CalculationSourceObject JSON export
5
5
  Author: Viktar B
6
6
  License: Apache-2.0
@@ -16,9 +16,17 @@ Dynamic: license-file
16
16
  # cs-object
17
17
 
18
18
  Author constrained `.cso.py` calculations with Python 3.11+. Runtime dependencies
19
- are the standard library only. Read [authoring](../../docs/authoring.md) before
20
- writing calculations and use [two-panel](../../examples/two-panel/README.md) for
21
- shared metadata and composed calls.
19
+ are the standard library only. Read the complete language and authoring contract
20
+ from your installed wheel before writing calculations:
21
+
22
+ ```sh
23
+ python -m cso_python authoring
24
+ python -m cso_python authoring --out authoring-contract.md
25
+ ```
26
+
27
+ The export includes the installed `cs-object` version and has no checkout-relative
28
+ links. It includes a complete composed-report recipe with a figure. The owning
29
+ source is [authoring.md](src/cso_python/authoring.md).
22
30
 
23
31
  ## Install and run
24
32
 
@@ -90,6 +98,31 @@ The captured path preflights local source and executes captured UTF-8 bytes.
90
98
  Older single-file exports retain the development exporter. This is trusted local
91
99
  calculation authoring, not isolation for hostile Python.
92
100
 
101
+ ## External adapters
102
+
103
+ `external_function` declares a single-file ordinary Python adapter with ordered
104
+ numeric inputs, named outputs, defaults and a reusable method explanation.
105
+ Generate its typed handle with the usual bindings command and import it from
106
+ `_cso_bindings._external.<declaration_module>`. Static tools capture the adapter
107
+ without importing it or requiring its scientific dependencies.
108
+
109
+ Use the handle inside a top-level generated calculation. It executes once per
110
+ authored call and captures every output, including unused diagnostics. Callers
111
+ select named outputs from the returned handle. External handles alone require
112
+ an active calculation context. Direct Python can also call the ordinary helper.
113
+
114
+ Adapters return native finite Python numbers, or a plain dictionary with exactly
115
+ the declared output keys. Convert library scalars explicitly and raise when the
116
+ algorithm fails. Adapter state is shared within a run and starts fresh in the
117
+ next run; installed dependency state is not a process sandbox. See the
118
+ [canonical examples](../../examples/external-functions/README.md).
119
+
120
+ The Python command-line consumer must explicitly advertise support with
121
+ `--supported-execution-protocol 4` before executing an external calculation.
122
+ The coordinated CSO CLI sends that capability automatically. `export` rejects
123
+ external calculations because standalone CSO cannot retain their call evidence.
124
+ Use full captured execution or prepared HTML/PDF instead.
125
+
93
126
  ## Code and checks
94
127
 
95
128
  [Public helpers](src/cso_python/__init__.py), [capture](src/cso_python/source.py),
@@ -97,7 +130,32 @@ calculation authoring, not isolation for hostile Python.
97
130
  [execution](src/cso_python/execution.py) and [bindings](src/cso_python/bindings.py)
98
131
  implement the pipeline described in [the code map](../../docs/code-map.md).
99
132
 
100
- With the wheel installed, run `python -I tests/run.py` from this package directory.
133
+ With the wheel installed, run `python -m pip install -r tests/requirements.txt`
134
+ and `python -I tests/run.py` from this package directory. The test-only mypy pin
135
+ checks positive and negative consumers of freshly generated bindings, including
136
+ keyword arguments and typed public result keys. Runtime dependencies stay empty.
101
137
  The tests use package-owned synthetic fixtures and temporary bindings; no root
102
138
  examples or Node are required. [Workspace integration](../../tests/integration/README.md)
103
139
  owns actual example, installed cross-package and PDF acceptance.
140
+
141
+
142
+ ## Release checks
143
+
144
+ Ship `src/cso_python/authoring.md` in every wheel and sdist. Update that one source
145
+ when the authoring contract changes. `python -m cso_python authoring` reads it
146
+ from the installed package; no initializer-time copy is maintained.
147
+
148
+ Before releasing, run the Python package tests and the repository's
149
+ `npm run test:initializer` against actual archives and a wheel. The installed
150
+ consumer checks the initializer's exact `requirements.txt` pin against wheel
151
+ metadata, exports the installed guide, checks local Markdown links and executes
152
+ the shipped composed-report recipe. A missing guide or stale exported copy fails
153
+ acceptance. Release CI runs these installed consumers before publication.
154
+
155
+ When upgrading the Python version used by new projects, update
156
+ `create-cs-object/template/requirements.txt` and release a new initializer version.
157
+ The two packages may have different version numbers. The exact dependency pin
158
+ selects the language contract; setup exports that wheel's guide each time it runs.
159
+ Existing projects can retain their pin. After an intentional upgrade, rerun setup
160
+ to refresh the local contract. Do not publish an initializer pin before that Python
161
+ version is available on PyPI.
@@ -9,27 +9,40 @@ src/cs_object.egg-info/top_level.txt
9
9
  src/cso_python/__init__.py
10
10
  src/cso_python/__main__.py
11
11
  src/cso_python/annotations.py
12
+ src/cso_python/authoring.md
12
13
  src/cso_python/authoring.py
13
14
  src/cso_python/bindings.py
15
+ src/cso_python/comparison.py
14
16
  src/cso_python/definitions.py
15
17
  src/cso_python/describe.py
16
18
  src/cso_python/execution.py
17
19
  src/cso_python/exporter.py
20
+ src/cso_python/external.py
18
21
  src/cso_python/function_calls.py
19
22
  src/cso_python/glyphs.py
23
+ src/cso_python/guidance.py
20
24
  src/cso_python/handles.py
21
25
  src/cso_python/notation.py
22
26
  src/cso_python/planner.py
23
27
  src/cso_python/py.typed
24
28
  src/cso_python/source.py
29
+ src/cso_python/source_plan.py
25
30
  tests/test_authoring_v2.py
31
+ tests/test_binding_types.py
32
+ tests/test_bindings.py
33
+ tests/test_boolean_call_outputs.py
34
+ tests/test_boolean_tables.py
26
35
  tests/test_cli.py
27
36
  tests/test_definitions.py
28
37
  tests/test_describe.py
29
38
  tests/test_execution.py
30
39
  tests/test_exporter.py
40
+ tests/test_external_functions.py
31
41
  tests/test_function_calls.py
42
+ tests/test_guidance.py
32
43
  tests/test_handle_reuse.py
44
+ tests/test_method_table.py
33
45
  tests/test_notation.py
34
46
  tests/test_notation_preflight.py
35
- tests/test_numeric_declarations.py
47
+ tests/test_numeric_declarations.py
48
+ tests/test_source_plan.py
@@ -7,16 +7,22 @@ from .authoring import (
7
7
  SectionSpec,
8
8
  SymbolSpec,
9
9
  calculation,
10
+ applicable,
11
+ boolean,
12
+ check,
10
13
  document_section,
11
14
  documented_result,
12
15
  figure,
13
16
  given,
17
+ method,
14
18
  section,
15
19
  symbol,
20
+ table,
16
21
  text,
17
22
  )
18
23
  from .execution import calculation_call
19
24
  from .handles import CalculationHandle, load_calculation
25
+ from .external import external_function, load_external
20
26
 
21
27
  __all__ = [
22
28
  "CalculationFunction",
@@ -24,15 +30,22 @@ __all__ = [
24
30
  "CalculationSpec",
25
31
  "SectionSpec",
26
32
  "SymbolSpec",
33
+ "applicable",
34
+ "boolean",
27
35
  "calculation",
28
36
  "calculation_call",
37
+ "check",
29
38
  "document_section",
30
39
  "documented_result",
31
40
  "figure",
32
41
  "given",
33
42
  "load_calculation",
43
+ "external_function",
44
+ "load_external",
34
45
  "CalculationHandle",
46
+ "method",
35
47
  "section",
36
48
  "symbol",
49
+ "table",
37
50
  "text",
38
51
  ]
@@ -8,6 +8,10 @@ from .exporter import add_export_arguments, export_from_args
8
8
 
9
9
  def main(argv: list[str] | None = None) -> int:
10
10
  arguments = sys.argv[1:] if argv is None else argv
11
+ if arguments and arguments[0] == "authoring":
12
+ from .guidance import authoring_from_argv
13
+
14
+ return authoring_from_argv(arguments[1:])
11
15
  if arguments and arguments[0] == "bindings":
12
16
  from .bindings import bindings_from_argv
13
17
  return bindings_from_argv(arguments[1:])
@@ -36,6 +40,7 @@ def main(argv: list[str] | None = None) -> int:
36
40
  commands.add_parser(
37
41
  "describe", help="Describe a calculation without executing authored code."
38
42
  )
43
+ commands.add_parser("authoring", help="Read version-matched calculation authoring guidance.")
39
44
  commands.add_parser("bindings", help="Generate typed calculation handles")
40
45
  add_export_arguments(export)
41
46
  return export_from_args(parser.parse_args(argv))