Merge pull request #149 from byuccl/next_release

v1.8.3

.gitignore

@@ -119,4 +119,8 @@ docs/source/auto_examples/
 # macOS Files
 **/.DS_Store
 
+# unzipped netlist files
+spydrnet/support_files/EDIF_netlists/*.edf
+spydrnet/support_files/verilog_netlists/*.v
+
 .vscode/settings.json

RELEASE.rst

@@ -1,3 +1,13 @@
+SpyDrNet 1.8.3
+--------------
+July 20, 2021
+
+* Bug fix in EDIF parser
+* Documentation updates
+* Added support for .edn
+* Added tests
+* Improved vo, vqm parsing
+
 SpyDrNet 1.8.2
 --------------
 June 24, 2021

docs/source/developer/contribute.rst

@@ -13,8 +13,8 @@ operations. Steps which need more explanation are highlighted below.
 2. Create a pull request with the updated code in the pre-release branch.
 3. Update the release notes
 4. Update the documentation and ensure it can build properly
-5. Commit those changes to the pull request
-6. Update the tag
+5. Commit and push those changes to the pull request. Accept the pull request when the checks have finished.
+6. Checkout to master branch and update the tag
 7. Build the python package (this will update the documentation’s version number)
 8. Build the documentation
 9. Create the release on Github
@@ -43,6 +43,8 @@ if you are missing packages run:
 
 >>> make install
 
+You may also need to run 'sudo apt install latexmk' and 'apt install texlive-latex-extra' to be able to create the pdf file.
+
 build the documentation without error as the html version will be put online at 
 the time of release and the pdf should be included in the releases files on
 Github

docs/source/developer/testing.rst

@@ -1,7 +1,7 @@
 Testing
 =======
 
-SpyDrNet developers strive to provide high quality code that is well tested. To help accomplish this goal, the built-in Python `Unit testing framework <https://docs.python.org/3/library/unittest.html>`_ is used in conjunction with the ``pytest`` `package <https://docs.pytest.org/>`_.
+SpyDrNet developers strive to provide high quality code that is well tested. To help accomplish this goal, the built-in Python `Unit testing framework <https://docs.python.org/3/library/unittest.html>`__ is used in conjunction with the ``pytest`` `package <https://docs.pytest.org/>`__.
 
 Running Tests
 -------------

docs/source/reference/Callback_Framework.rst

@@ -0,0 +1,75 @@
+Callback Framework
+##################
+
+SpyDrNet features a callback framework that allows developers to create plugins to watch a netlist data structure and register actions when certain changes are made. The callback framework was used to implement a namespace manager as a proof of concept. It could be used to implement additional design rule checks, a modification history log, or similar netlist watching features.
+
+Watched features
+****************
+
+the following table illustrates the currently implemented capabilities.
+
+
+* N - Netlist
+* L - Library
+* D - Definition
+* P - Port
+* C - Cable
+* I - Instance
+* W - Wire
+* p - Pin \*
+
+\* currently the pins do not have any callbacks implemented
+
+.. list-table:: Watched API Methods
+   :widths: 33 33 34
+   :header-rows: 1
+
+   * - Feature
+     - Watched Classes
+     - Parameters
+   * - Creation
+     - NLDPCIW--
+     - Created object
+   * - Add/Remove Wire
+     - ----C---
+     - cable, wire
+   * - Add/Remove Port
+     - --D-----
+     - definition, port
+   * - Add/Remove Child
+     - --D-----
+     - definition, child
+   * - Add/Remove Cable
+     - --D-----
+     - definition, cable
+   * - Modify Reference
+     - -----I--
+     - instance, reference
+   * - Add/Remove Definition
+     - -L------
+     - netlist, instance
+   * - Add/Remove Netlist
+     - N-------
+     - netlist, library
+   * - Add/Remove Pin
+     - ---P----
+     - port, pin
+   * - Connect/Disconnect Pin
+     - ------W-
+     - wire, pin
+   * - Set/Delete/Pop metadata
+     - NLDPCIW--
+     - element (object), key
+
+The feature column lists the function/behavior that is watched for. The "Watched SpyDrNet Classes" column highlights the SpyDrNet class on which the feature is watched. The parameters column lists the objects that are passed back.
+
+Implementation
+**************
+
+Implementing a call back listner involves creating a class that inherits and overrides from the existing CallbackListener class. Each of the desired methods will need to be overwritten in the inheriting class.
+
+Callbacks are made after sanity checks but before modifications are made to the datastructure. This allows users of the callback framework to prevent unwanted changes from taking place. This is an advantage in cases where an error can be detected before it is applied. Additional callbacks after the application of changes to the datastructure are currently not implemented to try keep the data structure light weight and quicker.
+
+Users of the callback feature must take into account that other users of the callbacks may later deny the modification. The order in which the callbacks are registered should match the order in which the callbacks are made. If it is important that the method succeeds after the callback is made, ensure that that callback listener is registered last or at least not before other callbacks that may prevent the proposed action.
+
+Additionally, since callbacks are made from within the API itself, be cautious when making API calls from within a callback. Infinite loops could be created.

docs/source/reference/NamespaceManager.rst

@@ -0,0 +1,52 @@
+Namespace Manager
+#################
+
+SpyDrNet's callback framework was leveraged to implement a namespace manager that will raise an exception if a naming rule is violated. The managers themselves also provide an example of how the callback framework can be leveraged.
+
+The namespace manager is a plugin that is loaded when the library is loaded. It will constantly be checking names and rejecting invalid or duplicate names. The active namespace can be set in code to allow for parsing in a different language or other cases where a valid name in the namespace may differ.
+
+Currently there are 2 namespaces implemented. One for EDIF and one called Default.
+
+
+Namespace Details (Default)
+***************************
+
+The namespace managers provide separate namespaces to be created based on element types. Both the default and EDIF namespaces allow for 1 namespace for Libraries indexed by the Netlist, 1 namespace for Definitions indexed by the Library and 3 namespaces for Ports, Cables, and Instances indexed by the Definition. This parallels EDIF and verilog Netlists well. Namespace scopes could be modified by creating a custom namespace manager (see the section below)
+
+The namespace manager checks each of the namespaces when an object is added, removed, or renamed to ensure that the new name does not clash with an old name. Name comparisons are made against the ".NAME" entry in each element's dictionary. This value is set when the .name setter is used as well so no additional care needs to be used. The implementation was done using the dictionary lookup on the key ".NAME" to provide a simpler template on which additional keys could be watched.
+
+The default manager accpets any name and has no restrictions, but it has the framework included to implement this when it is extended. The EDIF manager takes advantage of this feature.
+
+EDIF Details
+************
+
+EDIF has a relativly restrictive naming convention. Names are not case sensitive, Their max length is 255 characters, and they cannont contain many special characters. Most names are composed of uper and lower case letters, numbers, and underscores. The only exception is names that begin with a `&` character. To compensate for this some EDIF netlsits use an rename construct to provide a more human readable name and convert the name to something that fits within the namespace as an EDIF identifer.
+
+SpyDrNet's EDIF Namespace manager will look for case insensitive conflicts on the EDIF identifiers that are stored with the key "EDIF.identifier" along side the check for conflicts with the regular name in the default namespace.
+
+Additionally the EDIF namespace manager will check the EDIF identifiers for invalid characters or or lengths longer than 255 characters or 256 if it starts with an &.
+
+Using the namespace managers
+****************************
+
+Currently only "DEFAULT" and "EDIF" are avaiable namespaces. Verilog takes advantage of the "DEFAULT" namespace
+
+code required to turn the namespace to a different one. code::
+
+    >>> from spydrnet.plugins import namespace_manager
+    >>> 
+    >>> ns_default = namespace_manager.default #save the default just to be safe. (optional)
+    >>> namespace_manager.default = "EDIF" #can be set to "EDIF" or "DEFAULT"
+    >>> 
+    >>> do_something_cool() #new namespace rules will apply
+    >>> 
+    >>> namespace_manager.default = ns_default #set the default back (optional)
+
+The namespace manager that is selected will run in the background and watch for naming conflicts that occur as additions, modifications and removals take place on the netlist. Currently changing the namespace will not update the namespace with the existing netlist or details. Because of this, it is possible that unexpected errors may happen if the namespace is changed between operations (example: add a definition, change the namespace, remove a definition). This will likely be implemented at a future date.
+
+Creating a new Namespace
+************************
+
+The directory `spydrnet/plugins/namespace_manager/__init__.py` holds the callback logic while the other files in the directory `edif_namespace.py` and `default_namespace.py` hold the logic that checks if names are valid. Adding additional namespaces requires creating a new class that implements all of the functions present in the default_namespace.py's DefaultNamespace. The DefaultNamespace itself can be inherited and only the functions needed overwritten.
+
+Once implemented the __init__.py can be updated to include the namespace as a possible policy with an appropriate name string. Set the manager to be used with something like the example code above.

docs/source/reference/index.rst

@@ -12,3 +12,8 @@ Reference
    introduction
    element_data
    classes/index.rst
+   clone
+   uniquify
+   NamespaceManager
+   verilog_support
+   Callback_Framework