{"id":31789211,"url":"https://github.com/steffen-w/kicadfiles","last_synced_at":"2025-10-10T14:49:34.022Z","repository":{"id":315885816,"uuid":"1061145635","full_name":"Steffen-W/KiCadFiles","owner":"Steffen-W","description":"A comprehensive Python library for parsing and manipulating KiCad file formats with full S-expression support, type safety, and flexible error handling.","archived":false,"fork":false,"pushed_at":"2025-09-29T20:52:17.000Z","size":953,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-29T22:37:41.647Z","etag":null,"topics":["kicad","kicad-library","kicad-pcb","kicad-schematics","parser","s-expressions"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Steffen-W.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-21T10:38:35.000Z","updated_at":"2025-09-29T20:52:21.000Z","dependencies_parsed_at":"2025-09-21T12:28:01.255Z","dependency_job_id":"47037d70-f2ad-477f-a3fc-3d09cc9c07df","html_url":"https://github.com/Steffen-W/KiCadFiles","commit_stats":null,"previous_names":["steffen-w/kicadfiles"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Steffen-W/KiCadFiles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steffen-W%2FKiCadFiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steffen-W%2FKiCadFiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steffen-W%2FKiCadFiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steffen-W%2FKiCadFiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Steffen-W","download_url":"https://codeload.github.com/Steffen-W/KiCadFiles/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steffen-W%2FKiCadFiles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004184,"owners_count":26083689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kicad","kicad-library","kicad-pcb","kicad-schematics","parser","s-expressions"],"created_at":"2025-10-10T14:49:30.135Z","updated_at":"2025-10-10T14:49:34.013Z","avatar_url":"https://github.com/Steffen-W.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KiCadFiles\n\nA comprehensive Python library for parsing and manipulating KiCad file formats.\n\n[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)\n[![CI/CD](https://github.com/Steffen-W/KiCadFiles/workflows/CI%20Pipeline/badge.svg)](https://github.com/Steffen-W/KiCadFiles/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI version](https://badge.fury.io/py/kicadfiles.svg)](https://badge.fury.io/py/kicadfiles)\n[![Documentation](https://img.shields.io/badge/docs-sphinx-blue.svg)](https://steffen-w.github.io/KiCadFiles/)\n[![codecov](https://codecov.io/gh/Steffen-W/KiCadFiles/branch/master/graph/badge.svg)](https://codecov.io/gh/Steffen-W/KiCadFiles)\n\n📚 **[View Full Documentation](https://steffen-w.github.io/KiCadFiles/)** - Complete API reference and examples\n\n## Features\n\n- **Complete KiCad S-expression support**: \u003e200 classes representing KiCad tokens (missing tokens? [create an issue](https://github.com/Steffen-W/KiCadFiles/issues) with examples)\n- **Type-safe parsing**: Full Python type hints for all classes and methods\n- **Flexible error handling**: Three strictness modes (STRICT, FAILSAFE, SILENT)\n- **Round-trip parsing**: Parse KiCad files and convert back to S-expressions\n- **Minimal dependencies**: Self-contained S-expression parsing (no external dependencies)\n- **Extensive testing**: Comprehensive test suite ensuring reliability\n\n## Installation\n\n```bash\npip install kicadfiles\n```\n\n## Quick Start\n\n### Main File Format Classes\n\n```python\nfrom kicadfiles import (\n    KicadPcb, KicadSch, Footprint, KicadWks, KicadSymbolLib,\n    KicadProject, KiCadDesignRules, FpLibTable, SymLibTable,\n    KiCadTemplates\n)\n\n# PCB board (.kicad_pcb)\npcb = KicadPcb.from_file(\"board.kicad_pcb\")\n# pcb.save_to_file(\"output.kicad_pcb\")\n\n# Schematic (.kicad_sch)\nschematic = KicadSch.from_file(\"schematic.kicad_sch\")\n# schematic.save_to_file(\"output.kicad_sch\")\n\n# Footprint (.kicad_mod)\nfootprint = Footprint.from_file(\"component.kicad_mod\")\n# footprint.save_to_file(\"output.kicad_mod\")\n\n# Symbol library (.kicad_sym)\nsymbol_lib = KicadSymbolLib.from_file(\"library.kicad_sym\")\n# symbol_lib.save_to_file(\"output.kicad_sym\")\n\n# Worksheet (.kicad_wks)\nworksheet = KicadWks.from_file(\"template.kicad_wks\")\n# worksheet.save_to_file(\"output.kicad_wks\")\n\n# Project settings (.kicad_pro)\nproject = KicadProject.from_file(\"project.kicad_pro\")\n# project.save_to_file(\"output.kicad_pro\")\n\n# Design rules (.kicad_dru)\ndesign_rules = KiCadDesignRules.from_file(\"rules.kicad_dru\")\n# design_rules.save_to_file(\"output.kicad_dru\")\n\n# Footprint library table\nfp_lib_table = FpLibTable.from_file(\"fp-lib-table\")\n# fp_lib_table.save_to_file(\"output-fp-lib-table\")\n\n# Symbol library table\nsym_lib_table = SymLibTable.from_file(\"sym-lib-table\")\n# sym_lib_table.save_to_file(\"output-sym-lib-table\")\n```\n\n### Working with PCB Files\n\n```python\nfrom kicadfiles import KicadPcb, KiCadTemplates, NamedFloat\n\n# Load and modify existing PCB\npcb = KicadPcb.from_file(\"board.kicad_pcb\")\n\n# Access elements\nfor footprint in pcb.footprints:\n    print(f\"Footprint: {footprint.library_link} at ({footprint.at.x}, {footprint.at.y})\")\n\n# Create new PCB from template\nnew_pcb = KiCadTemplates.pcb()\nnew_pcb.setup.pad_to_mask_clearance = NamedFloat(\"pad_to_mask_clearance\", 0.05)\nnew_pcb.save_to_file(\"new_board.kicad_pcb\")\n```\n\n## API Overview\n\n### Core Classes\n\n- **NamedObject**: Base class for all KiCad objects\n- **ParseStrictness**: Enum controlling error handling (STRICT, FAILSAFE, SILENT)\n\n### Main File Format Classes\n\nThese classes represent complete KiCad file formats and support both `from_file()` and `save_to_file()` methods:\n\n- **KicadSymbolLib**: Symbol library files (.kicad_sym)\n- **KicadPcb**: PCB board files (.kicad_pcb)\n- **KicadSch**: Schematic files (.kicad_sch)\n- **KicadWks**: Worksheet files (.kicad_wks)\n- **Footprint**: Individual footprint files (.kicad_mod)\n- **KicadProject**: Project settings files (.kicad_pro)\n\n### Main Object Categories\n\n- **Base Types**: At, Size, Layer, Stroke, etc.\n- **Text and Documents**: TitleBlock, Page, Comment, etc.\n- **Pad and Drill**: Pad, Drill, Via, etc.\n- **Graphics**: Line, Circle, Arc, Polygon, etc.\n- **Symbol Library**: Symbol, Pin, Property, etc.\n- **Footprint Library**: Footprint, Model, Tags, etc.\n- **Zone System**: Zone, Hatch, FilledPolygon, etc.\n- **Board Layout**: General, Layers, Nets, etc.\n- **Schematic System**: Wire, Junction, Label, etc.\n\n## Error Handling with Strictness Modes\n\n```python\nfrom kicadfiles import At, ParseStrictness\n\n# STRICT mode: Raises exceptions for any parsing errors\ntry:\n    at_obj = At.from_sexpr(\"(at 10.0 20.0)\", ParseStrictness.STRICT)\nexcept ValueError as e:\n    print(f\"Parsing failed: {e}\")\n\n# FAILSAFE mode: Logs warnings and uses defaults for missing fields\nat_obj = At.from_sexpr(\"(at 10.0 20.0)\", ParseStrictness.FAILSAFE)\nprint(f\"Angle defaulted to: {at_obj.angle}\")  # Output: 0.0\n\n# SILENT mode: Silently uses defaults for missing fields\nat_obj = At.from_sexpr(\"(at 10.0 20.0)\", ParseStrictness.SILENT)\n```\n\n| Mode | Behavior |\n|------|----------|\n| **STRICT** | Raises `ValueError` on errors |\n| **FAILSAFE** | Logs warnings, uses defaults |\n| **SILENT** | Uses defaults silently |\n\nFor a complete overview of all classes and their module organization, see **[kicadfiles/CLASSES.md](kicadfiles/CLASSES.md)**.\n\n## Development\n\n### Setting up Development Environment\n\n```bash\ngit clone https://github.com/Steffen-W/KiCadFiles.git\ncd KiCadFiles\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest tests/ -v\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack .\nisort .\n\n# Linting\nflake8 kicadfiles/\n\n# Type checking\nmypy kicadfiles/\npyright kicadfiles/\n```\n\n### Documentation with sphinx\n\n```bash\ncd docs \u0026\u0026 make clean \u0026\u0026 make html \u0026\u0026 cd ..\n# Open docs/build/html/index.html in browser\n```\n\n### Coverage\n\n```bash\npytest --cov=kicadfiles --cov-report=html tests/\n# Open htmlcov/index.html in browser\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nIf you encounter any problems or have questions, please open an issue on the [GitHub repository](https://github.com/Steffen-W/KiCadFiles/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteffen-w%2Fkicadfiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteffen-w%2Fkicadfiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteffen-w%2Fkicadfiles/lists"}