luke
/
klayout
mirror of https://github.com/KLayout/klayout.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updating stubs and DRC/LVS doc

This commit is contained in:
Matthias Koefferlein 2024-04-30 19:27:34 +02:00
parent 05c129dd81
commit 43066284d5
4 changed files with 942 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/doc/doc/about/drc_ref_layer.xml
View File

@ -2255,7 +2255,11 @@ on polygons and edges (input1: red, input2: blue):
This method will copy the content of the layer to the specified output.
</p><p>
If a report database is selected for the output, the specification has to include a
category name and optionally a category description.
category name and optionally a category description. The category name can be an
array of strings - in that case, a hierarchy of categories is created
with the first array item being the top level category name.
Shapes are added to an existing category, if a category with the given
name already exists.
</p><p>
If the layout is selected for the output, the specification can consist of
one to three parameters: a layer number, a data type (optional, default is 0)

545
src/pymod/distutils_src/klayout/dbcore.pyi
View File

File diff suppressed because it is too large Load Diff

276
src/pymod/distutils_src/klayout/laycore.pyi
View File

@ -2512,6 +2512,266 @@ class Dispatcher:
is returned but no exception is thrown.
"""
class EditorHooks:
r"""
@brief An implementation base class for editor hooks
Editor hooks allow implementing technology-specific callbacks into the editor for example to implement visual feedback about DRC rules.
This class provides the basic interface. To implement callbacks, use the \EditorHooks class. You should not need to instantiate this class.
The following is an excample for editor hooks that add DRC space indicators for polygon-alike shapes,
It implements the shape creation protocol to capture new shapes and the modification protocol to capture shape manipulations. It displays a halo following hard-coded DRC rules to indicate the forbidden zones around the shapes:
@code
class MyEditorHooks < RBA::EditorHooks
def initialize()
register("editor_hooks_demo")
cleanup
# some demo values
@spaces = {
RBA::LayerInfo::new(1, 0) => [ 0.2, RBA::Region::Euclidian ],
RBA::LayerInfo::new(2, 0) => [ 0.5, RBA::Region::Projection ]
}
end
# Utilities
# pick the space value from layer or set to nil
def set_space_from_layer(layer_index)
lp = @layout.get_info(layer_index)
if @spaces[lp]
(s, m) = @spaces[lp]
@space = s / @layout.dbu
@metrics = m
else
@space = nil
end
end
def add_marker_from_shape(shape, trans)
if !@space
return # no space value set
end
p = shape.polygon
if !p
return # not a polygon-like object
end
r = RBA::Region::new
# maintain 2-point polygons for the first edge drawn
r.merged_semantics = (p.num_points != 2)
r.insert(p)
# compute DRC hull and prepare markers
r.drc_hull(@metrics, @space).each do |pp|
m = RBA::Marker::new(@view)
m.line_style = 2
m.vertex_size = 0
m.set_polygon(trans * pp)
@markers.append(m)
end
end
# setup session
def start(cv)
cleanup
@view = cv.view
@layout = cv.layout
end
# end session
def cleanup
@space = nil
@view = nil
@layout = nil
clear_markers
end
def clear_markers
@markers && @markers.each do |m|
# this is how a marker gets removed in Ruby:
m._destroy
end
@markers = []
end
# Shape creation protocol
def begin_create_shapes(cv, layer)
start(cv)
set_space_from_layer(layer.layer_index)
end
def begin_new_shapes
clear_markers
end
def create_shape(shape, trans)
add_marker_from_shape(shape, trans)
end
def end_create_shapes
cleanup
end
# Modification protocol
def begin_edit(cv)
start(cv)
end
def begin_edits
# create new markers
clear_markers
end
# transformation of a shape or instance
def transformed(path, applied, trans)
if path.shape
set_space_from_layer(path.layer)
add_marker_from_shape(path.shape, trans * applied)
end
end
# modification of a shape
def modified(path, shape, trans)
set_space_from_layer(path.layer)
add_marker_from_shape(shape, trans)
end
def end_edit
cleanup
end
end
# instantiation of the hooks object
MyEditorHooks::new
@/code
The EditorHooks class has been introduced in version 0.29.1.
"""
@property
def technology(self) -> None:
r"""
WARNING: This variable can only be set, not retrieved.
@brief sets the name of the technology the hooks are associated with
This will clear all technology associations and associate the hooks with that technology only.
"""
@classmethod
def new(cls) -> EditorHooks:
r"""
@brief Creates a new object of this class
"""
def __init__(self) -> None:
r"""
@brief Creates a new object of this class
"""
def _create(self) -> None:
r"""
@brief Ensures the C++ object is created
Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.
"""
def _destroy(self) -> None:
r"""
@brief Explicitly destroys the object
Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception.
If the object is not owned by the script, this method will do nothing.
"""
def _destroyed(self) -> bool:
r"""
@brief Returns a value indicating whether the object was already destroyed
This method returns true, if the object was destroyed, either explicitly or by the C++ side.
The latter may happen, if the object is owned by a C++ object which got destroyed itself.
"""
def _is_const_object(self) -> bool:
r"""
@brief Returns a value indicating whether the reference is a const reference
This method returns true, if self is a const reference.
In that case, only const methods may be called on self.
"""
def _manage(self) -> None:
r"""
@brief Marks the object as managed by the script side.
After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.
Usually it's not required to call this method. It has been introduced in version 0.24.
"""
def _unmanage(self) -> None:
r"""
@brief Marks the object as no longer owned by the script side.
Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.
Usually it's not required to call this method. It has been introduced in version 0.24.
"""
def add_technology(self, tech: str) -> None:
r"""
@brief Additionally associates the hooks with the given technology.
See also \clear_technologies.
"""
def clear_technologies(self) -> None:
r"""
@brief Clears the list of technologies the hooks are associated with.
See also \add_technology.
"""
def create(self) -> None:
r"""
@brief Ensures the C++ object is created
Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.
"""
def destroy(self) -> None:
r"""
@brief Explicitly destroys the object
Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception.
If the object is not owned by the script, this method will do nothing.
"""
def destroyed(self) -> bool:
r"""
@brief Returns a value indicating whether the object was already destroyed
This method returns true, if the object was destroyed, either explicitly or by the C++ side.
The latter may happen, if the object is owned by a C++ object which got destroyed itself.
"""
def for_technologies(self) -> bool:
r"""
@brief Returns a value indicating whether the hooks are associated with any technology.
"""
def is_const_object(self) -> bool:
r"""
@brief Returns a value indicating whether the reference is a const reference
This method returns true, if self is a const reference.
In that case, only const methods may be called on self.
"""
def is_for_technology(self, tech: str) -> bool:
r"""
@brief Returns a value indicating whether the hooks are associated with the given technology.
The method is equivalent to checking whether the \technologies list is empty.
"""
def name(self) -> str:
r"""
@brief Gets the name of the hooks object.
This is the name, the object was registered under in the system.
"""
def register(self, name: str) -> None:
r"""
@brief Registers the hooks in the system.
The hooks will not be active before they are registered in the system. Registration will also transfer object ownership to the system.
The name is arbitary, but should be unique. Upon registration, this hooks object will replace others with the same name already registered in the system. This will simplify debugging as you can re-run the same code, without accumulating hooks.
"""
def technologies(self) -> List[str]:
r"""
@brief Gets the list of technologies these hooks are associated with.
"""
class Image(BasicImage):
r"""
@brief An image to be stored as a layout annotation
@ -9157,6 +9417,14 @@ class PluginFactory:
r"""
@brief Creates a new object of this class
"""
def __copy__(self) -> PluginFactory:
r"""
@brief Creates a copy of self
"""
def __deepcopy__(self) -> PluginFactory:
r"""
@brief Creates a copy of self
"""
def __init__(self) -> None:
r"""
@brief Creates a new object of this class
@ -9256,6 +9524,10 @@ class PluginFactory:
This method has been introduced in version 0.27.
"""
def assign(self, other: PluginFactory) -> None:
r"""
@brief Assigns another object to self
"""
def create(self) -> None:
r"""
@brief Ensures the C++ object is created
@ -9273,6 +9545,10 @@ class PluginFactory:
This method returns true, if the object was destroyed, either explicitly or by the C++ side.
The latter may happen, if the object is owned by a C++ object which got destroyed itself.
"""
def dup(self) -> PluginFactory:
r"""
@brief Creates a copy of self
"""
def is_const_object(self) -> bool:
r"""
@brief Returns a value indicating whether the reference is a const reference

230
src/pymod/distutils_src/klayout/rdbcore.pyi
View File

@ -86,15 +86,31 @@ class RdbCategory:
This method returns true, if the object was destroyed, either explicitly or by the C++ side.
The latter may happen, if the object is owned by a C++ object which got destroyed itself.
"""
@overload
def each_item(self) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database which are associated with this category
This method has been introduced in version 0.23.
"""
@overload
def each_item(self) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database which are associated with this category (non-const version)
This method has been introduced in version 0.29.
"""
@overload
def each_sub_category(self) -> Iterator[RdbCategory]:
r"""
@brief Iterates over all sub-categories
The const version has been added in version 0.29.
"""
@overload
def each_sub_category(self) -> Iterator[RdbCategory]:
r"""
@brief Iterates over all sub-categories (non-const version)
"""
def is_const_object(self) -> bool:
r"""
@ -118,10 +134,19 @@ class RdbCategory:
@brief Gets the number of visited items in this category
The number of items includes the items in sub-categories of this category.
"""
@overload
def parent(self) -> RdbCategory:
r"""
@brief Gets the parent category of this category
@return The parent category or nil if this category is a top-level category
The const version has been added in version 0.29.
"""
@overload
def parent(self) -> RdbCategory:
r"""
@brief Gets the parent category of this category (non-const version)
@return The parent category or nil if this category is a top-level category
"""
def path(self) -> str:
r"""
@ -262,12 +287,20 @@ class RdbCell:
@brief Ensures the C++ object is created
Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.
"""
@overload
def database(self) -> ReportDatabase:
r"""
@brief Gets the database object that category is associated with
This method has been introduced in version 0.23.
"""
@overload
def database(self) -> ReportDatabase:
r"""
@brief Gets the database object that category is associated with (non-const version)
This method has been introduced in version 0.29.
"""
def destroy(self) -> None:
r"""
@brief Explicitly destroys the object
@ -280,26 +313,50 @@ class RdbCell:
This method returns true, if the object was destroyed, either explicitly or by the C++ side.
The latter may happen, if the object is owned by a C++ object which got destroyed itself.
"""
@overload
def each_item(self) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database which are associated with this cell
This method has been introduced in version 0.23.
"""
@overload
def each_item(self) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database which are associated with this cell (non-const version)
This method has been introduced in version 0.29.
"""
@overload
def each_reference(self) -> Iterator[RdbReference]:
r"""
@brief Iterates over all references
"""
@overload
def each_reference(self) -> Iterator[RdbReference]:
r"""
@brief Iterates over all references (non-const version)
This method has been introduced in version 0.23.
"""
def is_const_object(self) -> bool:
r"""
@brief Returns a value indicating whether the reference is a const reference
This method returns true, if self is a const reference.
In that case, only const methods may be called on self.
"""
def layout_name(self) -> str:
r"""
@brief Gets the name of the layout cell
For variants, this string is the name of the actual layout cell. If empty, the cell is assume to be called 'name'.
@return The layout cell name
This read-only attribute has been added in version 0.29.1.
"""
def name(self) -> str:
r"""
@brief Gets the cell name
The cell name is an string that identifies the category in the database. Additionally, a cell may carry a variant identifier which is a string that uniquely identifies a cell in the context of its variants. The "qualified name" contains both the cell name and the variant name. Cell names are also used to identify report database cell's with layout cells. @return The cell name
The cell name is an string that identifies the category in the database. Additionally, a cell may carry a variant identifier which is a string that uniquely identifies a cell in the context of its variants. The "qualified name" contains both the cell name and the variant name. Cell names are also used to identify report database cells with layout cells. For variants, the layout cell name can be specified explicitly with the \layout_name attribute (see \RdbDatabase#create_cell). The latter is available since version 0.29.1.
@return The cell name
"""
def num_items(self) -> int:
r"""
@ -311,7 +368,7 @@ class RdbCell:
"""
def qname(self) -> str:
r"""
@brief Gets the cell's qualified name
@brief Gets the qualified name of the cell
The qualified name is a combination of the cell name and optionally the variant name. It is used to identify the cell by name in a unique way.
@return The qualified name
"""
@ -324,7 +381,8 @@ class RdbCell:
def variant(self) -> str:
r"""
@brief Gets the cell variant name
A variant name additionally identifies the cell when multiple cells with the same name are present. A variant name is either assigned automatically or set when creating a cell. @return The cell variant name
A variant name additionally identifies the cell when multiple cells with the same name are present. A variant name is either assigned automatically or set when creating a cell.
@return The cell variant name
"""
class RdbItem:
@ -332,6 +390,21 @@ class RdbItem:
@brief An item inside the report database
An item is the basic information entity in the RDB. It is associated with a cell and a category. It can be assigned values which encapsulate other objects such as strings and geometrical objects. In addition, items can be assigned an image (i.e. a screenshot image) and tags which are basically boolean flags that can be defined freely.
"""
comment: str
r"""
Getter:
@brief Gets the common associated with this item as a string
@return The comment string
The comment string is an arbitrary string added by the user to the item.
This attribute has been added in version 0.29.1.
Setter:
@brief Sets the common associated with this item as a string
See \comment for a description of that attribute.
This attribute has been added in version 0.29.1.
"""
@property
def image(self) -> None:
r"""
@ -563,6 +636,11 @@ class RdbItem:
@brief Remove the tag with the given id from the item
If a tag with that ID does not exists on this item, this method does nothing.
"""
def remove_tags(self) -> None:
r"""
@brief Removes all tags from the item
This method has been introduced in version 0.29.1.
"""
class RdbItemValue:
r"""
@ -955,6 +1033,14 @@ class RdbReference:
@brief Ensures the C++ object is created
Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.
"""
@overload
def database(self) -> ReportDatabase:
r"""
@brief Gets the database object that category is associated with (non-const version)
This method has been introduced in version 0.29.
"""
@overload
def database(self) -> ReportDatabase:
r"""
@brief Gets the database object that category is associated with
@ -1041,6 +1127,14 @@ class ReportDatabase:
@param name The name of the database
The name of the database will be used in the user interface to refer to a certain database.
"""
def __copy__(self) -> ReportDatabase:
r"""
@brief Creates a copy of self
"""
def __deepcopy__(self) -> ReportDatabase:
r"""
@brief Creates a copy of self
"""
def __init__(self, name: str) -> None:
r"""
@brief Creates a report database
@ -1084,29 +1178,98 @@ class ReportDatabase:
Usually it's not required to call this method. It has been introduced in version 0.24.
"""
def apply(self, other: ReportDatabase) -> None:
r"""
@brief Transfers item attributes from one database to another for identical items
This method will identify items that are identical between the two databases and transfer item attributes from the 'other' database to this database. Transferable attributes are:
@ul
@li Images @/li
@li Item tags @/li
@/ul
Existing attributes in this database are overwritten.
Items are identical if
@ul
@li They belong to the same cell (by qname) @/li
@li They belong to the same category (by name) @/li
@li Their values are identical @/li
@/ul
Values are identical if their individual values and (optional) value tags are identical. Values tagged with a tag unknown to the other database are ignored. The order of values matters during the compare. So the value pair (17.0, 'abc') is different from ('abc', 17.0).
The intended application for this method is use for error waiving: as the waived attribute is a transferable attribute, it is possible to apply the waived flag from from a waiver database (the 'other' database) using this method.
This method has been added in version 0.29.1.
"""
def assign(self, other: ReportDatabase) -> None:
r"""
@brief Assigns another object to self
"""
@overload
def category_by_id(self, id: int) -> RdbCategory:
r"""
@brief Gets a category by ID
@return The (const) category object or nil if the ID is not valid
"""
@overload
def category_by_id(self, id: int) -> RdbCategory:
r"""
@brief Gets a category by ID (non-const version)
@return The (const) category object or nil if the ID is not valid
This non-const variant has been introduced in version 0.29.
"""
@overload
def category_by_path(self, path: str) -> RdbCategory:
r"""
@brief Gets a category by path
@param path The full path to the category starting from the top level (subcategories separated by dots)
@return The (const) category object or nil if the name is not valid
"""
@overload
def category_by_path(self, path: str) -> RdbCategory:
r"""
@brief Gets a category by path (non-const version)
@param path The full path to the category starting from the top level (subcategories separated by dots)
@return The (const) category object or nil if the name is not valid
This non-const variant has been introduced in version 0.29.
"""
@overload
def cell_by_id(self, id: int) -> RdbCell:
r"""
@brief Returns the cell for a given ID
@param id The ID of the cell
@return The cell object or nil if no cell with that ID exists
"""
@overload
def cell_by_id(self, id: int) -> RdbCell:
r"""
@brief Returns the cell for a given ID (non-const version)
@param id The ID of the cell
@return The cell object or nil if no cell with that ID exists
This non-const variant has been added version 0.29.
"""
@overload
def cell_by_qname(self, qname: str) -> RdbCell:
r"""
@brief Returns the cell for a given qualified name
@param qname The qualified name of the cell (name plus variant name optionally)
@return The cell object or nil if no such cell exists
"""
@overload
def cell_by_qname(self, qname: str) -> RdbCell:
r"""
@brief Returns the cell for a given qualified name (non-const version)
@param qname The qualified name of the cell (name plus variant name optionally)
@return The cell object or nil if no such cell exists
This non-const variant has been added version 0.29.
"""
def create(self) -> None:
r"""
@brief Ensures the C++ object is created
@ -1124,6 +1287,7 @@ class ReportDatabase:
@brief Creates a new sub-category
@param parent The category under which the category should be created
@param name The name of the category
Since version 0.29.1, 'parent' can be nil. In that case, a top-level category is created.
"""
@overload
def create_cell(self, name: str) -> RdbCell:
@ -1132,11 +1296,13 @@ class ReportDatabase:
@param name The name of the cell
"""
@overload
def create_cell(self, name: str, variant: str) -> RdbCell:
def create_cell(self, name: str, variant: str, layout_name: Optional[str] = ...) -> RdbCell:
r"""
@brief Creates a new cell, potentially as a variant for a cell with the same name
@param name The name of the cell
@param variant The variant name of the cell
@param layout_name For variants, this is the name of the layout cell. If empty, 'name' is used for the layout cell name.
The 'layout_name' argument has been added in version 0.29.1.
"""
@overload
def create_item(self, cell: RdbCell, category: RdbCategory) -> RdbItem:
@ -1302,34 +1468,90 @@ class ReportDatabase:
This method returns true, if the object was destroyed, either explicitly or by the C++ side.
The latter may happen, if the object is owned by a C++ object which got destroyed itself.
"""
def dup(self) -> ReportDatabase:
r"""
@brief Creates a copy of self
"""
@overload
def each_category(self) -> Iterator[RdbCategory]:
r"""
@brief Iterates over all top-level categories
"""
@overload
def each_category(self) -> Iterator[RdbCategory]:
r"""
@brief Iterates over all top-level categories (non-const version)
The non-const variant has been added in version 0.29.
"""
@overload
def each_cell(self) -> Iterator[RdbCell]:
r"""
@brief Iterates over all cells
"""
@overload
def each_cell(self) -> Iterator[RdbCell]:
r"""
@brief Iterates over all cells (non-const version)
This non-const variant has been added version 0.29.
"""
@overload
def each_item(self) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database
"""
@overload
def each_item(self) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database (non-const version)
This non-const variant has been added in version 0.29.
"""
@overload
def each_item_per_category(self, category_id: int) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database which are associated with the given category
@param category_id The ID of the category for which all associated items should be retrieved
"""
@overload
def each_item_per_category(self, category_id: int) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database which are associated with the given category (non-const version)
@param category_id The ID of the category for which all associated items should be retrieved
This non-const variant has been added in version 0.29.
"""
@overload
def each_item_per_cell(self, cell_id: int) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database which are associated with the given cell
@param cell_id The ID of the cell for which all associated items should be retrieved
"""
@overload
def each_item_per_cell(self, cell_id: int) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database which are associated with the given cell (non-const version)
@param cell_id The ID of the cell for which all associated items should be retrieved
This non-const variant has been added in version 0.29.
"""
@overload
def each_item_per_cell_and_category(self, cell_id: int, category_id: int) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database which are associated with the given cell and category
@param cell_id The ID of the cell for which all associated items should be retrieved
@param category_id The ID of the category for which all associated items should be retrieved
"""
@overload
def each_item_per_cell_and_category(self, cell_id: int, category_id: int) -> Iterator[RdbItem]:
r"""
@brief Iterates over all items inside the database which are associated with the given cell and category
@param cell_id The ID of the cell for which all associated items should be retrieved
@param category_id The ID of the category for which all associated items should be retrieved
This non-const variant has been added in version 0.29.
"""
def filename(self) -> str:
r"""
@brief Gets the file name and path where the report database is stored