Expert Raw API

najaeda ships two Python API levels:

• najaeda.netlist is the supported high-level API for most tools.

• najaeda.naja is the raw compiled extension module, historically also importable as top-level naja in some build layouts.

The raw layer is useful, but it is intentionally not the first documentation entry point. It exposes native SNL objects directly and assumes that callers understand database ownership, object lifetimes, uniquification, and the SNL hierarchy model.

When to use the raw API

Use najaeda.naja when you need to:

• construct SNL objects using native factory methods;

• call a native method that is not wrapped by najaeda.netlist;

• inspect exact SNL IDs, paths, occurrences, libraries, or databases;

• use live SystemVerilog frontend intent helpers;

• debug the high-level API or compare wrapper behavior against native state.

Prefer najaeda.netlist for application code that edits hierarchical designs. If you edit raw objects directly, automatic high-level uniquification does not protect you.

Importing the raw module

Use the package export in user code:

from najaeda import naja

print(naja.getVersion())
universe = naja.NLUniverse.get()

Some development and test layouts also place the extension on PYTHONPATH as top-level naja. Prefer from najaeda import naja in documentation and reusable scripts because it works with bundled package layouts too.

Importing the native module does not write a performance report by default. Set NAJA_PERF=1 to write naja_perf.log, or set NAJA_PERF to a file path to select another destination. An unset or empty value disables the performance report, which is appropriate when embedding Naja in a host Python process.

Object identity and hashing

Raw SNL objects returned by repeated accessor calls are not guaranteed to be the same Python wrapper object. Do not use id(obj) to identify nets, terms, instances, paths, occurrences, or other wrapped SNL objects across calls. Use == for equality and use the wrapped object itself as a dict key or set element when the object is hashable. Objects with a native NLID hash from that NLID. SNLPath and SNLOccurrence are hashable by composing the NLID values of their referenced objects. SNLAttribute is hashable from its name and typed value. Other raw value wrappers without an NLID are intentionally unhashable.

Relationship to high-level wrappers

High-level wrappers store or recover native objects internally:

High-level object	Typical raw object	Notes
najaeda.netlist.Instance	najaeda.naja.SNLInstance plus najaeda.naja.SNLPath	Carries occurrence context; edits may uniquify.
najaeda.netlist.Term	najaeda.naja.SNLTerm, najaeda.naja.SNLBitTerm, or najaeda.naja.SNLInstTerm	May represent top terms or instance terms.
najaeda.netlist.Net	najaeda.naja.SNLNet, najaeda.naja.SNLBitNet, or concatenated bits	Use high-level wrappers for hierarchical net edits.
najaeda.netlist.Equipotential	najaeda.naja.SNLEquipotential	Native object used for flat connectivity.
najaeda.netlist.Attribute	najaeda.naja.SNLAttribute	Metadata attached to SNL design objects.

Raw construction example

The exact factory signatures are native CPython bindings. The following pattern shows the intended ownership flow:

from najaeda import naja

universe = naja.NLUniverse.create()
db = naja.NLDB.create(universe)
lib = naja.NLLibrary.create(db, "work")
design = naja.SNLDesign.create(lib, "top")
universe.setTopDesign(design)

a = naja.SNLScalarTerm.create(design, naja.SNLTerm.Direction.Input, "a")
y = naja.SNLScalarTerm.create(design, naja.SNLTerm.Direction.Output, "y")
n = naja.SNLScalarNet.create(design, "n")

a.setNet(n)
y.setNet(n)

Object lifetime and safety

Raw objects are views of native C++ objects. After calling destroy() or after resetting/destroying the owning universe, database, library, or design, do not keep using Python objects that referenced the destroyed native object.

The raw API also exposes shared model state. Renaming, reconnecting, or destroying an object through a raw handle mutates the underlying SNL object directly. If the same model is instantiated in multiple places, that change can affect all occurrences unless you explicitly uniquify first.

SystemVerilog frontend intent helpers

The raw module includes expert helpers for live SystemVerilog frontend data:

• najaeda.naja.intent_available()

• najaeda.naja.live_compilation()

• najaeda.naja.ast_symbol_of()

• najaeda.naja.snl_objects_of()

• najaeda.naja.intent_parameters_of()

• najaeda.naja.intent_type_of()

• najaeda.naja.intent_package_member()

These helpers return plain Python data or capsules tied to the latest retained SystemVerilog frontend state. Treat capsules as opaque handles.

Raw module reference

The compiled extension exposes the following public objects in the current binding. Read this table as an expert index; the C++ SNL API remains the semantic source of truth.

Object	Main public methods and values
najaeda.naja.NLUniverse	create, destroy, get, getDB, getTopDB, setTopDB, getTopDesign, setTopDesign, getUserDBs, getSNLDesign, getObject, applyDLE, applyConstantPropagation, getMaxFanout, getMaxLogicLevel
najaeda.naja.NLDB	create, destroy, getID, getNLID, isTopDB, getLibraries, getLibrary, getGlobalLibraries, getPrimitiveLibraries, getTopDesign, loadVerilog, loadSystemVerilog, loadLibertyPrimitives, loadNajaIF, dumpNajaIF, dumpVerilog
najaeda.naja.NLLibrary	create, createPrimitives, getDB, getID, getNLID, getName, setName, isStandard, isPrimitives, getSNLDesign, getSNLDesigns, getLibrary
najaeda.naja.SNLDesign	create, createPrimitive, clone, destroy, getName, setName, getDB, getLibrary, getID, getNLID, getRevisionCount, getTerms, getTerm, getTermByID, getScalarTerms, getBusTerms, getBundleTerms, getNets, getNet, getScalarNets, getBusNets, getInstances, getInstance, getInstanceByID, getInstanceByIDList, getParameters, getParameter, getClockTerms, getAsyncResetTerms, getAsyncSetTerms, getSyncResetTerms, getSyncSetTerms, getDataInputTerms, getOutputTerms, setTruthTable, setTruthTables, getTruthTable, getTruthTableByOutputID, isConst0, isConst1, isConst, isBuf, isInv, isAnd, isNand, isOr, isNor, isXor, isXnor, isMux, dumpVerilog, dumpFullDotFile, dumpContextDotFile
najaeda.naja.SNLInstance	create, destroy, getName, setName, getID, getNLID, getDesign, getModel, getInstTerm, getInstTerms, getInstParameter, getInstParameters, getCombinatorialInputs, getCombinatorialOutputs
najaeda.naja.SNLTerm and term subclasses	Direction, getName, setName, getDirection, getDesign, getNet, setNet, getBits, getWidth, getNLID, getSourceLoc, hasSourceLoc
najaeda.naja.SNLNet and net subclasses	Type, getName, setName, getDesign, getBits, getWidth, getType, setType, getTypeAsString, isConstant, isConstant0, isConstant1, getComponents, getInstTerms, getBitTerms
najaeda.naja.SNLInstTerm	getInstance, getBitTerm, getNet, setNet, getDirection, getRole, getResetActiveLevel, is_clock, is_async_reset, is_async_set, is_sync_reset, is_sync_set, is_reset, is_enable, is_data, is_data_input, is_data_output
najaeda.naja.SNLTermRole	Clock, DataInput, DataOutput, AsyncReset, AsyncSet, SyncReset, SyncSet, Enable, MemoryReadAddress, MemoryReadData, MemoryWriteAddress, MemoryWriteData, MemoryWriteEnable, Other
najaeda.naja.SNLPath	empty, size, getInstances, getInstanceIDs, getHeadInstance, getTailInstance, getHeadPath, getTailPath, getDesign, getModel
najaeda.naja.SNLOccurrence	isInstanceOccurrence, getPath, getInstance, getInstTerm, getNetComponent, getDesign
najaeda.naja.SNLEquipotential	getTerms, getInstTermOccurrences, isConst0, isConst1, dumpDotFile
najaeda.naja.NLID	from_string, toTuple, getType, getDBID, getLibraryID, getDesignID, getDesignObjectID, getInstanceID, getBit, isDesign, isInstance, isNet, isTerm
najaeda.naja.LogicCone	FanIn, FanOut, getDirection, getRoot, getNodes, getLeaves, getNodeCount and snake_case aliases
Module functions	najaeda.naja.getVersion(), najaeda.naja.getGitHash(), najaeda.naja.snapshot_manifest(), najaeda.naja.setLogLevel(), najaeda.naja.addLogFile(), najaeda.naja.clearLogSinks(), najaeda.naja.installLoggingHandler(), najaeda.naja.log(), najaeda.naja.logInfo(), najaeda.naja.logWarn(), najaeda.naja.logCritical() plus the SystemVerilog intent helpers listed above

Detailed raw reference

When Sphinx can import the compiled extension, the following section exposes clickable class and method anchors generated from the raw binding itself. Documentation builders that do not have the binary available show the static expert reference above.