xorn.storage.Revision Class Reference

A particular state of the contents of a file. More...

Public Member Functions
def	__init__
	Create a new revision, either from scratch or by copying an existing one. More...
def	is_transient
	Return whether a revision can be changed. More...
def	finalize
	Prevent further changes to a revision. More...
def	get_objects
	Return a list of all objects in a revision. More...
def	object_exists
	Return whether an object exists in a revision. More...
def	get_object_data
	Get the data of an object in a revision. More...
def	get_object_location
	Get the location of an object in the object structure. More...
def	add_object
	Add a new object to a transient revision. More...
def	set_object_data
	Set the data of an object in a transient revision. More...
def	relocate_object
	Change the location of an object in the object structure of a transient revision. More...
def	copy_object
	Copy an object to a transient revision. More...
def	copy_objects
	Copy some objects to a transient revision. More...
def	delete_object
	Delete an object from a transient revision. More...
def	delete_objects
	Delete some objects from a transient revision. More...

Public Attributes
	transient
	Whether the revision is transient. More...

Detailed Description

A particular state of the contents of a file.

Definition at line 35 of file storage.py.

Constructor & Destructor Documentation

def xorn.storage.Revision.__init__	(		self,
			rev = None
	)

Create a new revision, either from scratch or by copying an existing one.

Parameters

rev	Revision to copy, or None.

There is a slight difference between creating two empty revisions and copying an empty one: only in the second case, objects of one revision will be valid in the other.

Exceptions

MemoryError

if there is not enough memory

Definition at line 47 of file storage.py.

Member Function Documentation

def xorn.storage.Revision.add_object	(		self,
			data
	)

Add a new object to a transient revision.

The object is appended to the end of the object list.

data must be an instance of one of the object data types (Arc, Box, Circle, Component, Line, Net, Path, Picture, or Text).

Returns

Returns the new object.

Exceptions

ValueError	if the revision isn't transient
TypeError	if data doesn't have a valid type
MemoryError	if there is not enough memory

Example:

rev = xorn.storage.Revision()

data = xorn.storage.Line()
data.x = 0.
data.y = 0.
data.width = 100.
data.height = 100.
data.line.width = 1.

ob = rev.add_object(data)

Definition at line 142 of file storage.py.

def xorn.storage.Revision.copy_object	(		self,
			rev,
			ob
	)

Copy an object to a transient revision.

Any objects attached to ob are copied as well, their copies being attached to the copy of ob, which is appended to the end of the object list.

Parameters

self	Destination revision (must be transient)
rev	Source revision (does not need to be transient)
ob	Object in the source revision which should be copied

Returns

Returns the copy of ob.

Exceptions

ValueError	if self isn't transient
KeyError	if ob doesn't exist in rev
MemoryError	if there is not enough memory

Definition at line 238 of file storage.py.

def xorn.storage.Revision.copy_objects	(		self,
			rev,
			sel
	)

Copy some objects to a transient revision.

Any objects attached to the objects are copied as well and attached to the corresponding new object. The copied objects are appended to the end of the object list in an unspecified order.

Parameters

self	Destination revision (must be transient)
rev	Source revision (does not need to be transient)
sel	Objects in the source revision which should be copied

Returns

Returns a selection containing the copied objects, excluding attached objects.

Exceptions

ValueError	if self isn't transient
MemoryError	if there is not enough memory

Definition at line 258 of file storage.py.

def xorn.storage.Revision.delete_object	(		self,
			ob
	)

Delete an object from a transient revision.

Any objects attached to ob are deleted as well.

The deleted object(s) stay valid and can later be re-added using set_object_data.

Returns

None

Exceptions

ValueError	if the revision isn't transient
KeyError	if ob doesn't exist in the revision

Definition at line 273 of file storage.py.

def xorn.storage.Revision.delete_objects	(		self,
			sel
	)

Delete some objects from a transient revision.

Any objects attached to a deleted object are deleted as well.

The deleted objects stay valid and can later be re-added using set_object_data.

Objects that don't exist in the revision are ignored.

Returns

None

Exceptions

ValueError

if the revision isn't transient

Definition at line 289 of file storage.py.

def xorn.storage.Revision.finalize

(

self

)

Prevent further changes to a revision.

When a revision is created, it is initially transient, i.e. changeable. However, it is typically not desired for a revision to change once it is in its desired state. Using this function, you can prevent further changes to the revision. It will still be possible to create a copy of the revision and change that.

Returns

None

Definition at line 76 of file storage.py.

def xorn.storage.Revision.get_object_data	(		self,
			ob
	)

Get the data of an object in a revision.

Changing the returned data will not have an effect on the object; use set_object_data to change the object.

Returns

Returns an instance of the appropriate data class.

Exceptions

KeyError	if ob doesn't exist in the revision
ValueError	if the object type is not supported (should not happen)
MemoryError	if there is not enough memory

Example:

data = rev.get_object_data(ob)
data.color = 3
rev.set_object_data(ob, data)

Definition at line 112 of file storage.py.

def xorn.storage.Revision.get_object_location	(		self,
			ob
	)

Get the location of an object in the object structure.

Returns

Returns a tuple (attached_to, pos) where attached_to is the object to which ob is attached and pos is the index of ob relative to its sibling objects.

Exceptions

KeyError

if ob doesn't exist in the revision

Definition at line 123 of file storage.py.

def xorn.storage.Revision.get_objects

(

self

)

Return a list of all objects in a revision.

The objects are returned in their actual order. Attached objects are listed after the object they are attached to.

Exceptions

MemoryError

if there is not enough memory

Example:

for ob in rev.get_objects():
    data = rev.get_object_data(ob)
    # do something with ob and data

Definition at line 89 of file storage.py.

def xorn.storage.Revision.is_transient

(

self

)

Return whether a revision can be changed.

When a revision is created, it is initially transient, i.e. changeable. This can be changed by calling finalize. After that, it can't be changed directly any more—you will have to create a transient copy if you want to change it again.

Definition at line 62 of file storage.py.

def xorn.storage.Revision.object_exists	(		self,
			ob
	)

Return whether an object exists in a revision.

Definition at line 94 of file storage.py.

def xorn.storage.Revision.relocate_object	(		self,
			ob,
			attach_to,
			insert_before
	)

Change the location of an object in the object structure of a transient revision.

This function performs two distinct operations:

1. Change the order in which an object is drawn and written to files as compared to its sibling objects.
2. Attach a schematic text object to a schematic net or component object. As far as this library is concerned, this will cause the text to be copied and deleted along with the net or component.

If attach_to is None, the object becomes un-attached. If ob and insert_before are identical, the revision is left unchanged.

Parameters

ob	The object which should be reordered and/or attached (must be Text if attach_to is not None)
attach_to	The object to which ob should be attached (must be Net or Component, or None)
insert_before	An object already attached to attach_to before which ob should be inserted, or None to append it at the end.

Returns

None

Exceptions

ValueError	if the revision isn't transient
KeyError	if ob or (if not None) attach_to or insert_before don't exist in the revision
ValueError	if attach_to is not None and ob is not a schematic text or attach_to is not a schematic net or schematic component
ValueError	if insert_before is not None and not attached to attach_to
MemoryError	if there is not enough memory

Example:

text_data = xorn.storage.Text()
text_data.text = "refdes=R1"

ob = rev.add_object(text_data)
rev.relocate_object(ob, component, None)

Definition at line 219 of file storage.py.

def xorn.storage.Revision.set_object_data	(		self,
			ob,
			data
	)

Set the data of an object in a transient revision.

If the object does not exist in the revision, it is created and appended to the end of the object list.

Parameters

ob	An object which has previously been returned by a Xorn function for either this revision, one of its ancestors, or a revision which has a common ancestor with it.
data	An instance of one of the object data types (Arc, Box, Circle, Component, Line, Net, Path, Picture, or Text). The type may be different from the previous type of the object but must be Net or Component if there are objects attached to ob, and must be Text if ob itself is attached to an object.

Returns

None

Exceptions

ValueError	if the revision isn't transient
TypeError	if data doesn't have a valid type
ValueError	if ob is attached to an object but the new object type wouldn't permit attaching the object
ValueError	if there are objects attached to ob but the new object type wouldn't permit attaching objects
MemoryError	if there is not enough memory

Example:

data = rev.get_object_data(ob)
data.color = 3
rev.set_object_data(ob, data)

Definition at line 176 of file storage.py.

Member Data Documentation

xorn.storage.Revision.transient

Whether the revision is transient.

Reading and writing this is equivalent to calling is_transient and finalize. Cannot be set to True.

Definition at line 53 of file storage.py.

---

The documentation for this class was generated from the following file:

• doc/api/xorn/storage.py