Usage highlights

Typing oriented

The askiff library is built around a Python static typing system (type annotations) and dataclasses. To ensure correct serialization, it is necessary to ensure type correctness when assigning to objects/fields defined in this library. The most robust way and one strongly recommended is to use type checkers (e.g. mypy, ty, …). Assigning an incorrect type object is likely to lead to runtime exceptions or corrupted files.

KiCad file structure mirroring

Most classes and their fields directly mirror the structure/map to objects in KiCad files.

The final typed fields or the _askiff_key field match the keyword used in KiCad files and should never be changed. If it is necessary to change them, other, related classes should probably be used. From the Python interface perspective, they are irrelevant.

Enum based values

KiCad files use multiple keywords and constant values to indicate object subtypes or some setting values.

To reduce the risk of spelling errors and make usage more clear, askiff abstracts this using 3 methods. It is highly recommended to use these mechanisms rather than work on raw values.

Enum

Python style enumerations, examples:

✅ Good
from askiff.gritems import DimensionOrthogonalOrientation
for dim in footprint.dimensions:
  if dim.orientation == DimensionOrthogonalOrientation.HORIZONTAL:
    ...
❌ Bad
for dim in footprint.dimensions:
  if str(dim.orientation) == '0':
    # Unclear what 0 means
    # May differ in future KiCad revisions
    ...
✅ Good
from askiff.board import ViaType
pad.type = ViaType.THRU
pad.type = ViaType.BLIND
# Spelling mistakes caught by type checker
# Nicely supported by LSP
❌ Bad
from askiff.board import ViaType
pad.type = '' # Q: What via type is this? A: thru hole
pad.type = 'blind' # May cause incorrect serialization
pad.type = ViaType('blind') # Risk of spelling mistake

Subclasses with hardcoded fields

One of the used patterns is a base abstract class with common fields (e.g. askiff.gritems.Dimension) and child classes (e.g. askiff.gritems.DimensionOrthogonal).

Base class is used in class typing but during deserialization it is automatically down casted to a specific subclass, based on a constant field with a keyword indicating the exact subtype.

This approach allows tighter typechecking and prevents setting fields that may be unsupported in this specific subclass.

This also works nicely with fine grained filtration of objects with multi level inheritance, see askiff.gritems.GrItem

✅ Good
from askiff.gritems import DimensionOrthogonal
for dim in footprint.dimensions:
  if isinstance(dim, DimensionOrthogonal):
    # Type checker/LSP know which fields are available
    ...
❌ Bad
for dim in footprint.dimensions:
  if dim.type == 'orthogonal':
    # Spelling mistake risk
    # Type check may later complain about unresolved attributes
    ...
✅ Good
from askiff.gritems import DimensionOrthogonal, DimensionRadial
dim = DimensionOrthogonal()
# copy just field that are present in new sub type
dim = DimensionRadial(**{k: v for k, v in fp.__dict__.items() if k in DimensionRadial.__dataclass_fields__})
# `dim` is still properly handled by LSP/type checker
❌ Bad
from askiff.gritems import DimensionOrthogonal
dim = DimensionOrthogonal()
dim.type = 'radial'
# New dimension type have different fields, resulting in file that can not be opened by KiCad

Class constants

See askiff.common_pcb.Layer

Highlighted classes

Refer to the documentation for more details about the most noteworthy classes:

Symbol types disambiguation

Last update: 2026-05-05