pythonscad-stl-generator 0.1.1__tar.gz

pythonscad_stl_generator-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nomike
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pythonscad_stl_generator-0.1.1/MANIFEST.in

@@ -0,0 +1,2 @@
+include docs/generate-pythonscad-stls.1
+include docs/generate-pythonscad-stls.1.md

pythonscad_stl_generator-0.1.1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: pythonscad-stl-generator
+Version: 0.1.1
+Summary: Render PythonSCAD design scripts to STL files, including customizer presets.
+Author: Nomike
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nomike/pythonscad-stl-generator
+Project-URL: Repository, https://github.com/nomike/pythonscad-stl-generator
+Project-URL: Issues, https://github.com/nomike/pythonscad-stl-generator/issues
+Project-URL: Changelog, https://github.com/nomike/pythonscad-stl-generator/blob/main/CHANGELOG.md
+Keywords: 3d,cad,openscad,pythonscad,stl,3d-printing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: docopt-ng<1,>=0.9
+Provides-Extra: dev
+Requires-Dist: build>=1.5; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=7; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Dynamic: license-file
+
+# PythonSCAD STL Generator
+
+PythonSCAD STL Generator is a small command line tool for batch-rendering
+PythonSCAD design files. It scans a directory for Python files that import
+`pythonscad`, renders each design with the `pythonscad` executable from
+`PATH`, and optionally renders once per customizer preset from a sibling JSON
+file.
+
+## Installation
+
+Install the published package with `pipx`:
+
+```sh
+pipx install pythonscad-stl-generator
+```
+
+Or install it into an existing environment with `pip`:
+
+```sh
+python -m pip install pythonscad-stl-generator
+```
+
+For development:
+
+```sh
+git clone https://github.com/nomike/pythonscad-stl-generator.git
+cd pythonscad-stl-generator
+python -m pip install -e ".[dev]"
+```
+
+PythonSCAD itself is not bundled. The tool expects a `pythonscad` executable to
+be available on `PATH`, or you can point to it explicitly with
+`--pythonscad=/path/to/pythonscad`.
+
+## Usage
+
+From a directory containing PythonSCAD designs:
+
+```sh
+generate-pythonscad-stls
+```
+
+The command writes STL files to `output/` by default. A Python file is treated
+as a design when it imports `pythonscad`, for example:
+
+```python
+from pythonscad import *
+
+width = add_parameter("width", 20)
+cube([width, width, width]).show()
+```
+
+Useful options:
+
+```sh
+generate-pythonscad-stls --output-dir stls
+generate-pythonscad-stls --pythonscad ~/bin/pythonscad
+generate-pythonscad-stls --format 3mf
+generate-pythonscad-stls --dry-run --verbose
+generate-pythonscad-stls --recursive
+```
+
+The generated PythonSCAD command includes `--trust-python`, because PythonSCAD
+requires that flag for command-line execution of Python input files.
+
+## Customizer Presets
+
+If `box.py` has a sibling `box.json`, the tool reads its top-level
+`parameterSets` object and renders once per preset:
+
+```json
+{
+  "parameterSets": {
+    "small": {
+      "width": "10"
+    },
+    "large": {
+      "width": "50"
+    }
+  },
+  "fileFormatVersion": "1"
+}
+```
+
+This produces files like:
+
+```text
+output/box-small.stl
+output/box-large.stl
+```
+
+Without a sibling preset file, the design renders once to `output/box.stl`.
+
+## Up-To-Date Checks
+
+Existing output files are skipped when they are newer than their inputs. For a
+plain design, the input is the `.py` file. For preset renders, both the `.py`
+file and the sibling `.json` preset file must be older than the output.
+
+Use `--force` to render everything regardless of timestamps.
+
+## Development
+
+Run tests:
+
+```sh
+python -m pytest
+```
+
+Run linting and formatting:
+
+```sh
+ruff check .
+ruff format .
+```
+
+Run all pre-commit hooks:
+
+```sh
+pre-commit run --all-files
+```
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE`.

pythonscad_stl_generator-0.1.1/README.md

@@ -0,0 +1,125 @@
+# PythonSCAD STL Generator
+
+PythonSCAD STL Generator is a small command line tool for batch-rendering
+PythonSCAD design files. It scans a directory for Python files that import
+`pythonscad`, renders each design with the `pythonscad` executable from
+`PATH`, and optionally renders once per customizer preset from a sibling JSON
+file.
+
+## Installation
+
+Install the published package with `pipx`:
+
+```sh
+pipx install pythonscad-stl-generator
+```
+
+Or install it into an existing environment with `pip`:
+
+```sh
+python -m pip install pythonscad-stl-generator
+```
+
+For development:
+
+```sh
+git clone https://github.com/nomike/pythonscad-stl-generator.git
+cd pythonscad-stl-generator
+python -m pip install -e ".[dev]"
+```
+
+PythonSCAD itself is not bundled. The tool expects a `pythonscad` executable to
+be available on `PATH`, or you can point to it explicitly with
+`--pythonscad=/path/to/pythonscad`.
+
+## Usage
+
+From a directory containing PythonSCAD designs:
+
+```sh
+generate-pythonscad-stls
+```
+
+The command writes STL files to `output/` by default. A Python file is treated
+as a design when it imports `pythonscad`, for example:
+
+```python
+from pythonscad import *
+
+width = add_parameter("width", 20)
+cube([width, width, width]).show()
+```
+
+Useful options:
+
+```sh
+generate-pythonscad-stls --output-dir stls
+generate-pythonscad-stls --pythonscad ~/bin/pythonscad
+generate-pythonscad-stls --format 3mf
+generate-pythonscad-stls --dry-run --verbose
+generate-pythonscad-stls --recursive
+```
+
+The generated PythonSCAD command includes `--trust-python`, because PythonSCAD
+requires that flag for command-line execution of Python input files.
+
+## Customizer Presets
+
+If `box.py` has a sibling `box.json`, the tool reads its top-level
+`parameterSets` object and renders once per preset:
+
+```json
+{
+  "parameterSets": {
+    "small": {
+      "width": "10"
+    },
+    "large": {
+      "width": "50"
+    }
+  },
+  "fileFormatVersion": "1"
+}
+```
+
+This produces files like:
+
+```text
+output/box-small.stl
+output/box-large.stl
+```
+
+Without a sibling preset file, the design renders once to `output/box.stl`.
+
+## Up-To-Date Checks
+
+Existing output files are skipped when they are newer than their inputs. For a
+plain design, the input is the `.py` file. For preset renders, both the `.py`
+file and the sibling `.json` preset file must be older than the output.
+
+Use `--force` to render everything regardless of timestamps.
+
+## Development
+
+Run tests:
+
+```sh
+python -m pytest
+```
+
+Run linting and formatting:
+
+```sh
+ruff check .
+ruff format .
+```
+
+Run all pre-commit hooks:
+
+```sh
+pre-commit run --all-files
+```
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE`.

pythonscad_stl_generator-0.1.1/VERSION.txt

@@ -0,0 +1 @@
+0.1.1

pythonscad_stl_generator-0.1.1/docs/generate-pythonscad-stls.1

@@ -0,0 +1,100 @@
+.TH GENERATE-PYTHONSCAD-STLS 1 "July 2026" "pythonscad-stl-generator" "User Commands"
+.SH NAME
+generate-pythonscad-stls \- render PythonSCAD designs and customizer presets
+.SH SYNOPSIS
+.B generate-pythonscad-stls
+[\fB--directory=\fR\fIDIR\fR] [\fB--output-dir=\fR\fIDIR\fR]
+[\fB--pythonscad=\fR\fIPATH\fR] [\fB--format=\fR\fIEXT\fR]
+[\fB--force\fR] [\fB--dry-run\fR] [\fB--recursive\fR]
+[\fB-v\fR|\fB--verbose\fR]
+.br
+.B generate-pythonscad-stls
+\fB-h\fR|\fB--help\fR
+.br
+.B generate-pythonscad-stls
+\fB--version\fR
+.SH DESCRIPTION
+.B generate-pythonscad-stls
+scans a directory for Python files that import
+.B pythonscad
+and renders each detected design by invoking the PythonSCAD command line
+application. It passes
+.B --trust-python
+automatically.
+.PP
+When a design has a sibling JSON file with a top-level
+.B parameterSets
+object, the design is rendered once for each named preset using PythonSCAD's
+.B -p
+and
+.B -P
+customizer options.
+.SH OPTIONS
+.TP
+.B -h, --help
+Show help text.
+.TP
+.B --version
+Show the program version.
+.TP
+.BI --directory= DIR
+Directory to scan for PythonSCAD designs. Defaults to the current directory.
+.TP
+.BI --output-dir= DIR
+Directory for generated output files. Relative paths are resolved below the
+scan directory. Defaults to
+.BR output .
+.TP
+.BI --pythonscad= PATH
+PythonSCAD executable to run. Defaults to
+.B pythonscad
+from
+.BR PATH .
+.TP
+.BI --format= EXT
+Output file extension and PythonSCAD export format. Defaults to
+.BR stl .
+.TP
+.B --force
+Render even when output files are newer than their inputs.
+.TP
+.B --dry-run
+Print render commands without executing them.
+.TP
+.B --recursive
+Search for designs recursively below the scan directory.
+.TP
+.B -v, --verbose
+Enable debug logging.
+.SH FILES
+.TP
+.I design.py
+PythonSCAD design script. The file is detected as a design when it imports
+.BR pythonscad .
+.TP
+.I design.json
+Optional customizer preset file with a top-level
+.B parameterSets
+object.
+.SH EXAMPLES
+.EX
+generate-pythonscad-stls
+.EE
+.PP
+.EX
+generate-pythonscad-stls --dry-run --verbose
+.EE
+.PP
+.EX
+generate-pythonscad-stls --pythonscad ~/bin/pythonscad --output-dir stls
+.EE
+.SH EXIT STATUS
+.TP
+.B 0
+All requested renders completed successfully, or no designs were found.
+.TP
+.B 2
+Command line input, scan directory, or preset JSON was invalid.
+.TP
+.B other non-zero status from pythonscad
+At least one render command failed; the PythonSCAD exit code is returned.

pythonscad_stl_generator-0.1.1/docs/generate-pythonscad-stls.1.md

@@ -0,0 +1,99 @@
+# generate-pythonscad-stls(1)
+
+## Name
+
+generate-pythonscad-stls - render PythonSCAD designs and customizer presets
+
+## Synopsis
+
+```text
+generate-pythonscad-stls [--directory=<dir>] [--output-dir=<dir>]
+                         [--pythonscad=<path>] [--format=<ext>]
+                         [--force] [--dry-run] [--recursive]
+                         [-v | --verbose]
+generate-pythonscad-stls -h | --help
+generate-pythonscad-stls --version
+```
+
+## Description
+
+`generate-pythonscad-stls` scans a directory for Python files that import
+`pythonscad` and renders each detected design by invoking the PythonSCAD
+command line application. It passes `--trust-python` automatically.
+
+When a design has a sibling JSON file with a top-level `parameterSets` object,
+the design is rendered once for each named preset using PythonSCAD's `-p` and
+`-P` customizer options.
+
+## Options
+
+`-h`, `--help`
+: Show help text.
+
+`--version`
+: Show the program version.
+
+`--directory=<dir>`
+: Directory to scan for PythonSCAD designs. Defaults to the current directory.
+
+`--output-dir=<dir>`
+: Directory for generated output files. Relative paths are resolved below the
+scan directory. Defaults to `output`.
+
+`--pythonscad=<path>`
+: PythonSCAD executable to run. Defaults to `pythonscad` from `PATH`.
+
+`--format=<ext>`
+: Output file extension and PythonSCAD export format. Defaults to `stl`.
+
+`--force`
+: Render even when output files are newer than their inputs.
+
+`--dry-run`
+: Print render commands without executing them.
+
+`--recursive`
+: Search for designs recursively below the scan directory.
+
+`-v`, `--verbose`
+: Enable debug logging.
+
+## Files
+
+`<design>.py`
+: PythonSCAD design script. The file is detected as a design when it imports
+`pythonscad`.
+
+`<design>.json`
+: Optional customizer preset file with a top-level `parameterSets` object.
+
+## Examples
+
+Render designs in the current directory:
+
+```sh
+generate-pythonscad-stls
+```
+
+Preview the commands that would be run:
+
+```sh
+generate-pythonscad-stls --dry-run --verbose
+```
+
+Use a specific PythonSCAD binary and output directory:
+
+```sh
+generate-pythonscad-stls --pythonscad ~/bin/pythonscad --output-dir stls
+```
+
+## Exit Status
+
+`0`
+: All requested renders completed successfully, or no designs were found.
+
+`2`
+: Command line input, scan directory, or preset JSON was invalid.
+
+Any other non-zero status from `pythonscad`
+: At least one render command failed; the PythonSCAD exit code is returned.

pythonscad_stl_generator-0.1.1/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pythonscad-stl-generator"
+dynamic = ["version"]
+description = "Render PythonSCAD design scripts to STL files, including customizer presets."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Nomike" },
+]
+keywords = ["3d", "cad", "openscad", "pythonscad", "stl", "3d-printing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Manufacturing",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics :: 3D Modeling",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "docopt-ng>=0.9,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.5",
+    "pytest>=8",
+    "pytest-cov>=7",
+    "ruff>=0.15",
+]
+
+[project.scripts]
+generate-pythonscad-stls = "pythonscad_stl_generator.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/nomike/pythonscad-stl-generator"
+Repository = "https://github.com/nomike/pythonscad-stl-generator"
+Issues = "https://github.com/nomike/pythonscad-stl-generator/issues"
+Changelog = "https://github.com/nomike/pythonscad-stl-generator/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.dynamic]
+version = { file = "VERSION.txt" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pythonscad_stl_generator = ["py.typed"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.format]
+quote-style = "double"

pythonscad_stl_generator-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pythonscad_stl_generator-0.1.1/src/pythonscad_stl_generator/__init__.py

@@ -0,0 +1,10 @@
+"""Tools for batch-rendering PythonSCAD designs."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pythonscad-stl-generator")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

pythonscad_stl_generator-0.1.1/src/pythonscad_stl_generator/cli.py

@@ -0,0 +1,92 @@
+"""Command line interface for PythonSCAD STL generation."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+from docopt import docopt
+
+from . import __version__
+from .discovery import discover_designs
+from .presets import PresetError
+from .render import plan_jobs, run_jobs
+
+USAGE = """PythonSCAD STL Generator.
+
+Usage:
+  generate-pythonscad-stls [--directory=<dir>] [--output-dir=<dir>]
+                           [--pythonscad=<path>] [--format=<ext>]
+                           [--force] [--dry-run] [--recursive]
+                           [-v | --verbose]
+  generate-pythonscad-stls -h | --help
+  generate-pythonscad-stls --version
+
+Options:
+  -h --help                 Show this screen.
+  --version                 Show the version.
+  --directory=<dir>         Directory to scan for PythonSCAD designs [default: .].
+  --output-dir=<dir>        Directory to save generated files to [default: output].
+  --pythonscad=<path>       PythonSCAD executable to run [default: pythonscad].
+  --format=<ext>            Output file extension/export format [default: stl].
+  --force                   Render even when output files are up to date.
+  --dry-run                 Print commands without executing them.
+  --recursive               Search for designs recursively below the scan directory.
+  -v --verbose              Show debug messages.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI and return a process-style exit code."""
+    arguments = docopt(USAGE, argv=argv, version=f"generate-pythonscad-stls {__version__}")
+    _configure_logging(verbose=bool(arguments["--verbose"]))
+
+    directory = Path(str(arguments["--directory"])).resolve()
+    output_dir = Path(str(arguments["--output-dir"]))
+    if not output_dir.is_absolute():
+        output_dir = directory / output_dir
+
+    if not directory.is_dir():
+        logging.error("%s is not a directory", directory)
+        return 2
+
+    try:
+        designs = discover_designs(directory, recursive=bool(arguments["--recursive"]))
+        if not designs:
+            logging.info("No PythonSCAD designs found in %s", directory)
+            return 0
+
+        jobs = plan_jobs(
+            designs,
+            output_dir=output_dir,
+            output_format=str(arguments["--format"]),
+            pythonscad=str(arguments["--pythonscad"]),
+            base_dir=directory,
+        )
+    except PresetError as error:
+        logging.error("%s", error)
+        return 2
+
+    logging.info("Planned %d render job(s) from %d design(s)", len(jobs), len(designs))
+    return run_jobs(
+        jobs,
+        force=bool(arguments["--force"]),
+        dry_run=bool(arguments["--dry-run"]),
+    )
+
+
+def _configure_logging(*, verbose: bool) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.INFO,
+        format="%(levelname)s: %(message)s",
+    )
+
+
+def _entrypoint() -> NoReturn:
+    raise SystemExit(main())
+
+
+if __name__ == "__main__":
+    sys.exit(main())