svgo 0.1.0__tar.gz

svgo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xmodar
+
+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.

svgo-0.1.0/PKG-INFO

@@ -0,0 +1,432 @@
+Metadata-Version: 2.4
+Name: svgo
+Version: 0.1.0
+Summary: Pure-Python SVG path editing, optimization, matrix geometry, measurement, sanitization, viewport editing, validation, tracing, and centerline reconstruction.
+Keywords: svg,path,optimizer,matrix,measurement,sanitize,viewbox,viewport,validation,trace,centerline,cli
+Author: xmodar
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/xmodar/svgo
+Project-URL: Repository, https://github.com/xmodar/svgo
+Project-URL: Issues, https://github.com/xmodar/svgo/issues
+Description-Content-Type: text/markdown
+
+# svgo
+
+`svgo` is a pure-Python SVG toolchain for path editing, SVG optimization,
+PNG icon tracing, centerline reconstruction, geometry conversion, matrix
+transforms, measurement, sanitization, viewBox/viewport edits, and SVG
+inspection. It ships as an importable Python package and as a single `svgo`
+command-line program.
+
+The package has no required runtime dependencies. If `numpy` is installed,
+some centerline distance-transform work can use accelerated array operations;
+otherwise the standard-library fallback is used.
+
+## Features
+
+- Edit SVG path data with ordered operations: translate, scale, affine matrix,
+  rotate, relative/absolute serialization, subpath reversal, origin changes,
+  and path optimization profiles.
+- Optimize whole SVG files with Python implementations of common
+  SVGO-style cleanup and minification operations.
+- Trace simple PNG icons into filled SVG paths without shelling out to
+  external tracing tools.
+- Convert filled stroke outlines into approximate stroked centerlines.
+- Convert SVG geometry primitives to path data and create common affine
+  matrices from Python.
+- Measure path/SVG length, bounds, and point-at-length coordinates.
+- Set, fit, and resize root SVG `viewBox`, `width`, and `height` values.
+- Validate SVG XML, inspect dimensions/element counts/fonts, and run
+  structural conversions such as shape-to-path conversion, plain cleanup,
+  CSS style inlining, sanitization, and transform flattening.
+- Use the same functionality from Python APIs or from the documented CLI.
+
+## Installation
+
+From PyPI, once published:
+
+```bash
+python -m pip install svgo
+```
+
+From this repository:
+
+```bash
+python -m pip install .
+```
+
+For local development with `uv`:
+
+```bash
+uv sync
+uv run svgo --help
+```
+
+## CLI
+
+The CLI entry point is `svgo`. It is organized into short subcommands, each
+with a one-letter alias:
+
+```bash
+svgo path   --path "<d>" [--op OP ...] [--svgo]                         # alias: p
+svgo path   --input icon.svg --output icon.out.svg --select all|N|N,N --op OP
+svgo opt    --input icon.svg --output icon.min.svg [optimization options] # alias: o
+svgo trace  --input icon.png --output traced.svg [trace options]          # alias: t
+svgo trace2 --input icon.png --output traced.svg [VTracer options]        # alias: t2
+svgo center --input outline.svg --output stroke.svg [centerline options]  # alias: c
+svgo info   --input icon.svg                                             # alias: i
+svgo validate --input icon.svg [--strict]                                # alias: v
+svgo measure --input icon.svg                                            # alias: m
+svgo sanitize --input icon.svg --output safe.svg                         # alias: s
+svgo viewbox --input icon.svg --fit-content --output fitted.svg          # alias: b
+svgo convert --input icon.svg --output converted.svg [conversion options] # alias: x
+svgo plugins                                                             # alias: l
+```
+
+Every command supports `--help`:
+
+```bash
+svgo --help
+svgo path --help
+svgo opt --help
+svgo trace --help
+svgo trace2 --help
+svgo center --help
+svgo info --help
+svgo validate --help
+svgo measure --help
+svgo sanitize --help
+svgo viewbox --help
+svgo convert --help
+```
+
+## Path Editing
+
+Path operations are applied in order with repeated `--op` flags:
+
+```bash
+svgo path --path "M10 10h5v5z" --op "matrix(-1,0,0,1,30,0)" --minify
+svgo p --input icon.svg --output edited.svg --select 0,2 --op translate:2,-1 --op optimize:safe
+```
+
+Supported operations:
+
+- `translate:dx,dy`
+- `scale:kx,ky`
+- `matrix:a,b,c,d,e,f` or `matrix(a,b,c,d,e,f)`
+- `rotate:ox,oy,degrees`
+- `relative`
+- `absolute`
+- `reverse` or `reverse:itemIndex`
+- `origin:itemIndex` or `origin:itemIndex:subpath`
+- `cubics`, `cubic`, `to-cubics`, or `toCubics`
+- `optimize:safe`, `optimize:size`, `optimize:closed`, `optimize:all`
+- `optimize:remove-useless,use-shorthands,use-hv,use-relative-absolute,use-reverse,use-close-path,remove-orphan-dots`
+
+The affine matrix uses SVG convention:
+
+```text
+x' = a*x + c*y + e
+y' = b*x + d*y + f
+```
+
+Arcs are converted to cubic Beziers during arbitrary affine transforms so
+reflections, rotations, scales, and skews stay fully Python based.
+
+## SVG Optimization
+
+`svgo opt` optimizes SVG documents. `svgo path --svgo` applies the same SVG
+optimizer after path edits:
+
+```bash
+svgo opt --input icon.svg --output icon.min.svg --svgo-multipass --svgo-precision 3
+svgo o --input icon.svg --svgo-disable cleanupIds --svgo-plugin removeDimensions
+svgo opt --input icon.svg --svgo-preset none --svgo-plugin convertShapeToPath --svgo-plugin sortAttrs
+svgo l
+```
+
+Supported options include:
+
+- `--svgo-preset default|none`
+- `--svgo-plugin NAME[:JSON]`
+- `--svgo-disable NAME`
+- `--svgo-precision N`
+- `--svgo-multipass`
+- `--svgo-pretty`
+- `--svgo-indent N`
+- `--svgo-eol lf|crlf`
+- `--svgo-final-newline`
+- `--svgo-datauri base64|enc|unenc`
+- `--svgo-config FILE`
+
+`--svgo-config` accepts JSON files and Python-readable TOML files. JavaScript
+SVGO configs are intentionally rejected because this implementation does not
+execute Node.js.
+
+## PNG Tracing
+
+PNG tracing has two modes. `trace` is the dependency-free pixel tracer: it
+decodes non-interlaced 8-bit PNGs with the standard library, groups visible
+pixels, traces connected-component boundaries, and writes filled SVG paths.
+
+```bash
+svgo trace --input icon.png --output traced.svg --mode palette --curve-mode pixel --max-colors 8 --quantize 24 --min-area 8
+```
+
+Modes:
+
+- `palette`: group pixels into dominant quantized colors.
+- `alpha`: trace a single alpha mask using the most common visible color.
+- `exact`: keep exact quantized color buckets.
+
+Useful options:
+
+- `--curve-mode pixel|exact`: keep exact per-pixel boundaries. This preserves
+  the original tracer behavior.
+- `--drop-white`
+- `--alpha-threshold N`
+- `--white-threshold N`
+- `--quantize N`
+- `--max-colors N`
+- `--min-area N`
+- `--scale N`
+- `--decimals N`
+- `--title TEXT`
+
+For higher-quality curve fitting, use `trace2`/`t2`. It calls the real
+[VTracer](https://github.com/visioncortex/vtracer) Python package when
+installed, or a `vtracer` CLI on `PATH`. The default values match VTracer's
+web-app defaults and the FreeConvert-style controls:
+
+```bash
+svgo trace2 --input icon.png --output traced.svg
+uv run --with vtracer svgo trace2 --input icon.png --output traced.svg
+svgo t2 --input icon.png --output traced.svg --curve-mode spline --filter-speckle 4 --color-precision 6 --gradient-step 16
+```
+
+VTracer options:
+
+- `--color-mode color|binary`
+- `--hierarchical stacked|cutout` or `--clustering stacked|cutout`
+- `--color-precision N`
+- `--gradient-step N`
+- `--filter-speckle N`
+- `--curve-mode pixel|polygon|spline`
+- `--corner-threshold N`
+- `--segment-length N`
+- `--max-iterations N`
+- `--splice-threshold N`
+- `--path-precision N`
+
+## Centerline Reconstruction
+
+Centerline reconstruction converts filled stroke outlines into approximate
+stroked paths by flattening path data, rasterizing with even-odd fill,
+skeletonizing with Zhang-Suen thinning, estimating stroke width, and tracing
+the skeleton.
+
+```bash
+svgo center --path "M0 0L100 0L100 20L0 20Z" --emit path
+svgo c --input traced.svg --output centerline.svg --svg-paths all --mode all --simplify 4
+```
+
+Important options:
+
+- `--emit path|svg|d`
+- `--mode longest|all`
+- `--scale N`
+- `--max-size N`
+- `--curve-samples N`
+- `--simplify N`
+- `--min-length N`
+- `--stroke-width auto|N`
+- `--linecap VALUE`
+- `--linejoin VALUE`
+- `--polyline`
+- `--svg-paths first|all`
+- `--keep-failed`
+
+Centerline output is intentionally approximate. For production icon work,
+render and inspect the result before final minification.
+
+## Inspection And Conversion
+
+`svgo info` prints structured JSON metadata:
+
+```bash
+svgo info --input icon.svg
+svgo i --input icon.svg --compact
+```
+
+`svgo validate` checks SVG XML and reports structural issues. Warnings do not
+make the command fail unless `--strict` is used:
+
+```bash
+svgo validate --input icon.svg
+svgo v --input icon.svg --strict --json
+```
+
+`svgo measure` reports path/SVG length and axis-aligned bounds. It accepts raw
+path data, SVG files, or text files containing path data:
+
+```bash
+svgo measure --path "M0 0H10V10H0Z" --decimals 3
+svgo m --input icon.svg --compact
+svgo m --path "M0 0H10V10" --at 15
+```
+
+`svgo sanitize` removes active or unsafe content while keeping normal static
+SVG geometry:
+
+```bash
+svgo sanitize --input icon.svg --output icon.safe.svg
+svgo s --input icon.svg --remove-external-refs --remove-styles
+```
+
+`svgo viewbox` edits root viewport metadata:
+
+```bash
+svgo viewbox --input icon.svg --set "0 0 24 24" --remove-dimensions
+svgo b --input icon.svg --fit-content --padding 1 --precision 2
+svgo b --input icon.svg --width 48 --height 48
+```
+
+`svgo convert` runs pure-Python structural conversions. With no conversion
+flags it converts basic shapes to paths:
+
+```bash
+svgo convert --input shapes.svg --output paths.svg
+svgo x --input drawing.svg --output plain.svg --to-plain
+svgo x --input transformed.svg --output flat.svg --shapes-to-paths --flatten-transforms
+svgo x --input styled.svg --output inline.svg --inline-styles
+svgo x --input source.svg --output converted.svg --all --precision 3
+```
+
+Conversion options:
+
+- `--to-plain`: remove common editor metadata and editor-specific attributes.
+- `--shapes-to-paths`: convert `rect`, `circle`, `ellipse`, `line`,
+  `polyline`, and `polygon` to `path`.
+- `--flatten-transforms`: bake supported transforms into path coordinates.
+- `--flatten-groups`: collapse empty unstyled groups.
+- `--inline-styles`: inline simple style-element rules into presentation
+  attributes.
+- `--sanitize`: remove scripts, event handlers, and unsafe links before
+  conversion.
+- `--all`: enable every conversion pass.
+- `--precision N`: control generated numeric precision.
+
+## Python API
+
+```python
+from svgo import (
+    PathData,
+    centerline_path_data,
+    circle_to_path,
+    get_svg_info,
+    fit_viewbox_svg,
+    inline_styles_svg,
+    optimize_svg,
+    path_metrics,
+    path_to_cubics,
+    rect_to_path,
+    resize_svg,
+    sanitize_svg,
+    set_viewbox_svg,
+    trace_png,
+    transform_2d,
+    translate_2d,
+    validate_svg,
+)
+
+path = PathData.parse("M0 0L10 0L10 10Z")
+path.transform((1, 0, 0, 1, 2, -1))
+path.optimize("safe")
+print(path.to_string(decimals=3, minify=True))
+
+svg = optimize_svg("<svg><rect width='10' height='10'/></svg>")
+shape = rect_to_path(0, 0, 24, 12, rx=2, decimals=3, minify=True)
+cubic = path_to_cubics("M0 0L10 0Q15 0 15 5", decimals=3, minify=True)
+x, y = transform_2d(translate_2d(10, 5), 1, 2)
+report = validate_svg("<svg viewBox='0 0 10 10'/>")
+metrics = path_metrics("M0 0H10V10H0Z", decimals=3)
+safe_svg = sanitize_svg("<svg onload='x()'><path d='M0 0H1'/></svg>")
+fitted_svg = fit_viewbox_svg("<svg><path d='M2 3H6V7H2Z'/></svg>")
+```
+
+The lower-level modules are:
+
+- `svgo.pathdata`
+- `svgo.geometry`
+- `svgo.measure`
+- `svgo.viewport`
+- `svgo.inspect_svg`
+- `svgo.svg_optimize`
+- `svgo.raster_trace`
+- `svgo.centerline`
+
+## Reference Tools
+
+These projects are useful reference points for SVG feature coverage, command
+shape, and API expectations:
+
+- [SVGO](https://github.com/svg/svgo): Node.js SVG optimizer and plugin
+  ecosystem.
+- [Scour](https://github.com/scour-project/scour): Python SVG optimizer and
+  cleaner.
+- [svgpathtools](https://github.com/mathandy/svgpathtools): Python path,
+  Bezier, geometry, length, and bounds utilities.
+- [svg.path](https://github.com/regebro/svg.path): Python SVG path parser and
+  path object model.
+- [svg-matrix-python](https://github.com/Emasoft/svg-matrix-python): Python
+  wrapper around SVG matrix conversion and validation workflows.
+- [Yqnn/svg-path-editor](https://github.com/Yqnn/svg-path-editor): SVG path
+  editing UI and path operation reference implementation.
+- [svg-path-commander](https://github.com/thednp/svg-path-commander):
+  TypeScript path parsing, normalization, geometry, and transformation tools.
+- [Iconify Tools](https://github.com/iconify/tools): TypeScript SVG import,
+  validation, cleanup, and export tooling.
+- [resvg/usvg](https://github.com/linebender/resvg): Rust SVG rendering and
+  static SVG simplification/reference implementation.
+- [VTracer](https://github.com/visioncortex/vtracer): Rust raster-to-vector
+  tracing tool.
+
+## Development
+
+This repository uses uv's native `uv_build` backend and has no required runtime
+dependencies.
+
+```bash
+uv run python -m unittest discover -s tests
+uv build
+```
+
+## Publishing
+
+PyPI publishing is handled by GitHub Actions Trusted Publishing through
+`.github/workflows/publish.yml`. The PyPI pending publisher must match this
+repository, the `publish.yml` workflow filename, and the `pypi` environment.
+
+To publish a release, update `project.version`, commit the change, and push a
+matching tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow verifies that the pushed tag equals `v{project.version}`, runs the
+test suite, builds the wheel and source distribution with `uv`, then publishes
+to PyPI with Trusted Publishing.
+
+The package targets Python 3.11 and newer.