pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk-0.6.3.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: pycforge-sdk
+Version: 0.6.3
+Summary: Conversion-extension authoring SDK with an optional PySide6 desktop
+License-Expression: GPL-3.0-only
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: gui
+Requires-Dist: PySide6<7,>=6.8; extra == "gui"
+Dynamic: license-file
+
+<img src="https://res.cloudinary.com/vppzdwxg/image/upload/v1793376351/pcf_sdk_banner.png" alt="PyCForge SDK" width="640">
+
+# PyCForge SDK 0.6.3
+
+PyCForge SDK is the development kit for creating conversion imports for PyCForge.
+Define supported library operations, write their documentation and examples,
+check the generated C, and build a `.pcfplugin` package for use through `*import`.
+
+Designed for human developers and AI tools, the SDK offers a desktop workspace,
+a command-line interface, and a Python API. All three use the same project files,
+conversion services, and verification rules.
+
+## A workspace for conversion imports
+
+- **Start with a working example:** choose scalar math, named parameters, NumPy,
+  JSON, or independently named array and structured-value libraries from the connected engine's starters.
+- **Define your library:** give its operations names and descriptions, using the
+  conversion capabilities supplied by PyCForge.
+- **Explain how to use it:** include parameter descriptions, return values,
+  practical limits, and examples in the package's searchable offline Help.
+- **Find what needs attention:** scan for incomplete fields, missing examples,
+  and verification that needs repeating. Open a finding to reach its field.
+- **Check the result:** convert examples to C, compile and run the declared tests,
+  and compare their results with your expectations.
+- **Build and register:** create a verified `.pcfplugin` package, then register it
+  with PyCForge when you are ready to use it.
+
+## Capabilities supplied by PyCForge
+
+PyCForge supplies the SDK's conversion operations, starter projects, authoring
+forms, method explanations, and Help. Its Crucible folder contains a versioned
+workbench definition and JSON schema, alongside the catalogue and import manuals.
+The SDK reads these descriptions without carrying its own list of libraries.
+After updating the selected PyCForge installation, reconnect the SDK to refresh
+that information. Compatible engine
+additions, including new default imports and their Help, become available without
+requiring a matching SDK release.
+
+The SDK application is installed separately. Changes to its desktop, command-line
+tools, or support for an incompatible engine interface require a separate SDK
+update. Connecting refreshes information from the installed PyCForge; it does
+not download or install either application. Reverify your projects after updating
+PyCForge, the SDK, or the C compiler.
+
+## Install and open
+
+Use Python 3.11–3.13 and install PyCForge separately. Install the SDK desktop from
+its wheel:
+
+```sh
+python -m pip install "./pycforge_sdk-0.6.3-py3-none-any.whl[gui]"
+pycforge-sdk-ui
+```
+
+On Windows, `py` can be used in place of `python`. For command-line, Python API,
+or AI automation without the desktop, omit `[gui]`. The desktop includes PySide6;
+the SDK without the desktop has no required third-party dependencies. Add
+`--upgrade` to the install command when installing an updated SDK wheel.
+
+The desktop looks for PyCForge when it opens. It checks your last successful
+connection first, then common Python installations and environment folders.
+A startup panel shows progress. If several installations are found, choose the
+version and location you want; the SDK remembers a successful connection.
+
+If PyCForge cannot be found, choose **Locate PyCForge**. Select its installation,
+Python environment, or installed SDK support folder (`pycforge/crucible/landscape`).
+The picker provides drive shortcuts, including C: on Windows. The SDK finds and
+validates the matching interpreter; a source folder by itself needs a working
+engine installation. **Continue offline** opens local projects and any cached
+reference without connecting.
+
+**Refresh** reloads the selected engine's capabilities. **Engine and tools** contains
+advanced interpreter and compiler settings, **Find installed**, and **This Python**
+for a shared environment. You can also select `python.exe` directly; Windows
+virtual environments keep it in `Scripts`, and Linux/macOS environments use
+`bin/python`. PyCForge's About dialog shows the exact interpreter under
+**Distribution → SDK Python**.
+
+The SDK and PyCForge can use separate Python environments. Searches check known
+locations without scanning entire drives. Environments kept elsewhere can be
+selected manually. Discovery and connection install nothing.
+
+## Create your first import
+
+1. Choose **New**, select a starter, and give the project a folder and author.
+2. Use **Edit extension** to complete the project, functions, Help, and test
+   examples. Save your changes before scanning.
+3. Choose **Scan** and follow its findings. The scanner shows whether the project
+   needs editing, verification, or is ready to package.
+4. Choose **Verify fixtures** to compile and run the saved test examples. Install
+   a C compiler supported by the selected engine before this step.
+5. Choose **Package** after verification passes. Packaging checks that the project,
+   documentation, tests, and tools still match the verified result.
+6. Register the package through the SDK's **Tools** menu or PyCForge's
+   **Register Conversion Imports** dialog. Select **Runtime** in PyCForge and use
+   `*import your_namespace as alias` in the source you want to convert.
+
+Building a package and registering it are separate actions. A registered package's
+**Import Help** explains its exact supported operations and examples.
+
+## Conversion coverage
+
+The connected engine determines the available operations and their rules.
+The supplied starters cover three useful families:
+
+| Family | What you can define |
+| --- | --- |
+| Scalar operations | Numeric functions and constants, documented input and result types, checked numeric limits, and supported optional or named parameters. Starters include scalar math and independent named-parameter examples. |
+| Array operations | One-dimensional finite `float64` arrays: creation, copies, addition, subtraction, multiplication, division, negation, absolute value, square root, concatenation, and minimum/maximum values or their first matching indices. Starters include NumPy and an independent vector namespace. |
+| Structured-value codecs | JSON loads and dumps with Unicode escaping, explicit separator options, lists/tuples and string-key dictionaries. The bounded profile uses int64, finite float64, at most 64 nested containers and 1 MiB of text; hooks and streams are unsupported. Starters include JSON and an independent record namespace. |
+
+Array and structured-value definitions use four ordinary fields: operation identity, exported name,
+operation choice, and summary. PyCForge supplies their signatures, storage, and
+cleanup rules. Authors provide the explanations and test cases.
+
+You can create additional library namespaces using supported operations; the SDK
+is not limited to math and NumPy. Each function must map to an available conversion
+implementation. Registering a library name does not make all of that Python
+library convertible. Multidimensional arrays, views, general broadcasting, other
+array data types, and arbitrary native dependencies are outside the supplied
+array contracts. Engine reference and Import Help describe the exact boundaries.
+
+## Command line and AI automation
+
+Use `pycforge-sdk --json discover` to list validated engine installations.
+Add `discover --location "/path/to/environment"` to check a specific location.
+Python clients can call `discover_engines()` from `pycforge_sdk` for the same
+structured result; discovery does not replace the reference cache. Use the
+`workbench` command or `SDK.workbench()` to inspect engine-owned forms, bundled
+imports, and Help through the same public backend.
+
+Use the command line from scripts or AI development tools. Replace
+`/path/to/engine/python` with the interpreter containing PyCForge; quote paths that
+contain spaces.
+
+```sh
+pycforge-sdk --engine-python /path/to/engine/python connect
+pycforge-sdk --engine-python /path/to/engine/python templates
+pycforge-sdk --engine-python /path/to/engine/python new ./cube-root --author "Your name"
+```
+
+The default starter demonstrates a cube-root conversion. Edit its `project.json`,
+documentation, test sources, and expected results for your intended use. Then run:
+
+```sh
+pycforge-sdk --engine-python /path/to/engine/python scan ./cube-root
+pycforge-sdk --engine-python /path/to/engine/python verify ./cube-root --compiler gcc
+pycforge-sdk --engine-python /path/to/engine/python readiness ./cube-root --compiler gcc
+pycforge-sdk --engine-python /path/to/engine/python build ./cube-root --compiler gcc --output ./cube-root.pcfplugin
+```
+
+Register the result explicitly with `register ./cube-root.pcfplugin`, using the
+same engine selection. Use `methods` and `describe ArrayFunction` to explore the
+engine reference, or `new --template TEMPLATE_ID` to select another starter.
+
+Pass `--json` before a command to receive structured results, diagnostic codes,
+and field locations. AI tools can inspect these results, correct project data,
+and repeat the same scan, verify, and package workflow used by a human author.
+Treat a nonzero exit code as an unsuccessful operation; do not infer approval
+from descriptive text.
+
+## Python API
+
+Use the same SDK service directly from Python. This example lists the starter
+projects available from the selected engine:
+
+```python
+from pycforge_sdk import SDK
+
+sdk = SDK(engine_python="/path/to/engine/python", cache="./sdk-cache")
+result = sdk.templates()
+if not result.ok:
+    raise RuntimeError(result.to_dict())
+
+for template in result.data["templates"]:
+    print(template["id"], template["description"])
+```
+
+The API also provides project creation and editing, inspection, conversion,
+verification, packaging, and registration. Each operation returns an `Outcome`
+with an `ok` flag and structured results. Human and AI clients use the same
+checks; authors remain responsible for the intended behavior and expected test
+results.
+
+## Help and practical requirements
+
+Press **F1** for the searchable guide and conversion-import manuals supplied by
+the connected PyCForge. The topic list follows the engine's bundled imports. A
+small getting-started guide remains available before connection. **Engine reference**
+explains available methods, parameters, results, and examples. Cached reference remains
+available when the engine cannot be reached; conversion, verification, and
+packaging require a compatible connected engine.
+
+Native fixture verification follows the selected engine's supported host and
+compiler profile. The supplied profile currently supports Linux with a GNU-style
+C compiler. Desktop browsing and project editing do not require running native
+tests. **Verify fixtures** explicitly compiles and executes the declared examples;
+browsing the reference and scanning project data do not run them.
+
+Passing verification means the declared test cases matched their expected
+results. It does not establish correctness for every possible input or platform.
+Changes to project data, Help, tests, or the selected tools require verification
+again before packaging. Review the package's documented limits when using its
+conversion imports.
+
+## License
+
+PyCForge SDK is free software under the GNU General Public License v3.0 only.
+The distribution includes `LICENSE`.