TikZBase¶

Author: Marcel Simader
Date: 11.07.2021

New in version v0.1.0.

TikZValue¶

Type alias for a TikZ key value.

alias of Union[AnyStr, int, float]

TikZWriteable¶

class TikZWriteable(required_packages, required_tikz_libraries)¶

Abstract base class for all TikZ objects which can be written to a TeXHandler. This class requires all subclasses to implement the to_tikz(), __hash__(), and __eq__() methods. The latter two are required in order to store these objects in sets and dictionaries. TikZWriteable objects should only compare equal if they are semantically equal.

The method __str__() is final and calls the abstract method to_tikz().

Parameters

required_packages (Collection[AnyStr]) – a collection of the names of the packages which are required to use a subclass of this class
required_tikz_libraries (Collection[AnyStr]) – a collection of the names of the TikZ libraries which are required to use a subclass of this class

__register_required_package__(*package)¶

Registers one or multiple required packages with this instance.

__register_required_tikz_library__(*library)¶

Registers one or multiple required TikZ libraries with this instance.

property required_packages: Tuple¶

Returns: the packages required to use this class in a document

property required_tikz_libraries: Tuple¶

Returns: the TikZ libraries required to use this class in a document

abstract to_tikz()¶

Converts this object to a TikZ string.

abstract __hash__()¶

Return hash(self).

abstract __eq__(other)¶

Return self==value.

TikZNamed¶

class TikZNamed(required_packages, required_tikz_libraries)¶

Abstract base class for a TikZWriteable object which can be defined in a tikzpicture and then referenced by its name. All subclasses of this class must implement the name(), and definition() methods. The final methods __str__(), and to_tikz() are mapped to the abstract method name().

The final methods __hash__(), and __eq__() compare two TikZNamed objects based solely on an instance check and the return value of the abstract method name(). This means that two TikZNamed objects with the same name are treated as being equal, regardless of their semantic contents (as is the case in TikZ itself).

Parameters

required_packages (Collection[AnyStr]) – a collection of the names of the packages which are required to use a subclass of this class
required_tikz_libraries (Collection[AnyStr]) – a collection of the names of the TikZ libraries which are required to use a subclass of this class

abstract property name: str¶

Returns: the TikZ name of this object as string

abstract property definition: str¶

Returns: the definition string of this object

final to_tikz()¶

Converts this object to a TikZ string.

TikZDefinesWriteable¶

class TikZDefinesWriteable(required_packages, required_tikz_libraries, required_writeable_objs)¶

Abstract base class for marking a subclass as keeping TikZWriteable objects in an ordered definition set. Each object registered with an instance of this class must inherit from TikZWriteable and (optionally) be of the type specified by the generic type variable.

This class is useful when one desires to build up more complex TikZ objects. For example, the TikZStyle class inherits from TikZDefinesWriteable[TikZColor], since each TikZ style also stores a number of TikZColor objects, which implement TikZNamed.

The handling of these TikZWriteable object is solved internally in the TikZPicture class.

Warning

This class internally stores each registered named object as a dictionary, so the objects will be compared using the __eq__ and __hash__ methods. Only the least recently registered object is kept, if two objects of the same type and same name are registered. See the documentation of TikZWriteable, and TikZNamed for details on these methods.

Parameters

required_packages (Collection[AnyStr]) – a collection of the names of the packages which are required to use a subclass of this class
required_tikz_libraries (Collection[AnyStr]) – a collection of the names of the TikZ libraries which are required to use a subclass of this class

__register_writeable_object__(*writeable_obj)¶

Register one or multiple TikZWriteable instances with this instance.

property required_writeable_objects: Iterator[SEPTeX.TikZBase._TW]¶

Returns: the required TikZWriteable objects used by this instance

property required_named_objects: Iterator[SEPTeX.TikZBase.TikZNamed]¶

Returns: the uniquely-named required TikZNamed objects used by this instance

TikZColor¶

class TikZColor(name, value, mode='rgb', *, generate_unique_name=False)¶

TikZColor represents an RGB color definition. Each color has a name, either 3 or 4 values and a mode. These color instances need to be registered with the TikZPicture instance before they can be used. Multiple colors can share the same name but they may be overwritten by each another, with the color registered at the most recent time being the used version.

The mode can be one of two values:

rgb for int or float values in the interval [0;1], or
RGB for int values in the interval [0;255]

Colors of length 3 represent RED, GREEN and BLUE, while colors with length 4 add an addition ALPHA channel at the end.

Various arithmetic operations are implemented for this class. The following syntax is used for all binary arithmetic operations (the same also applies for the right-handed arithmetic operations, but in reverse):

\[\circ \in \left\{ +, -, *, /, //, \%, ** \right\}\]

\[ \begin{align}\begin{aligned}\text{color} \circ \lambda &:\Longleftrightarrow \left( \text{r} \circ \lambda, \text{g} \circ \lambda, \text{b} \circ \lambda[, \text{a} \circ \lambda] \right)\\\text{color} \circ (x, y, z[, w]) &:\Longleftrightarrow \left( \text{r} \circ x, \text{g} \circ y, \text{b} \circ z[, \text{a} \circ w]\right)\\\text{color1} \circ \text{color2} &:\Longleftrightarrow \text{color1} \circ \left(\text{r}, \text{g}, \text{b}[, \text{a}]\right)_{\text{color2}}\end{aligned}\end{align} \]

Parameters

name (AnyStr) – the name to register this color instance under
value (ColorTuple) – the RGB[A] value of this color
mode (Literal['rgb', 'RGB']) – the mode of representing the color
generate_unique_name (bool) – keyword-only argument that indicates whether or not the class should automatically try to make colors unique by adding parts of the hash to the end of the name, this exists mainly to make arithmetic operations on colors easier to handle TODO make this part of TikZNamed by default

Raises

ValueError – if the value tuple is neither 3 nor 4 values long, or the types of the tuple do not match the constraints given by mode
NotImplementedError – if mode is not one of the listed literals

ColorTuple¶

Shorthand for a tuple of either 3 or 4 T.

alias of Union[Tuple[SEPTeX.TikZBase._N, SEPTeX.TikZBase._N, SEPTeX.TikZBase._N], Tuple[SEPTeX.TikZBase._N, SEPTeX.TikZBase._N, SEPTeX.TikZBase._N, SEPTeX.TikZBase._N]]

property raw_name: str¶

Returns: the raw name, different from name() since this does not include opacity

property name: str¶

Returns: a string containing the full name to be used in a TikZ context

property definition: str¶

Returns: a string containing the xcolor definition of this color for the preamble of a LaTeX document

property value: ColorTuple¶

Returns: the tuple data of this color

property mode: str¶

Returns: the mode of this color

property red: SEPTeX.TikZBase._N¶

Returns: the red channel

property green: SEPTeX.TikZBase._N¶

Returns: the green channel

property blue: SEPTeX.TikZBase._N¶

Returns: the blue channel

property alpha: Optional[SEPTeX.TikZBase._N]¶

Returns: the alpha channel if present or None

add_alpha(value)¶

Adds an alpha channel at opacity value to this color.

Parameters: value (SEPTeX.TikZBase._N) – the value of the new alpha channel
Returns: the new color with 4 channels, if the color already has 4 channels this function will return the original color
Return type: SEPTeX.TikZBase.TikZColor[SEPTeX.TikZBase._N]

remove_alpha()¶

Removes the alpha channel of this color.

Returns: the new color with 3 channels, if the color already had 3 channels this function will return the original color
Return type: SEPTeX.TikZBase.TikZColor[SEPTeX.TikZBase._N]

TikZArrowDirection¶

class TikZArrowDirection(value)¶: TikZArrowDirection is an enum which helps to track which direction an arrow of TikZArrow is pointing. It contains the values NONE, LEFT, RIGHT, and BOTH.

TikZArrow¶

class TikZArrow(value)¶

TikZArrow is an enumeration of TikZ arrow head types. An arrow enum variable has three values associated with it:

the name of the type, which only holds internal relevance

the TikZ key of the type, which is used in the TikZ source

the TikZArrowDirection of the type, which indicates which way the arrow is pointing

LINE¶

LEFT¶

RIGHT¶

LEFT_RIGHT¶

IN_LEFT¶

IN_RIGHT¶

IN_LEFT_RIGHT¶

LEFT_STUMP¶

RIGHT_STUMP¶

LEFT_RIGHT_STUMP¶

LEFT_LATEX¶

RIGHT_LATEX¶

LEFT_RIGHT_LATEX¶

LEFT_LATEX_PRIME¶

RIGHT_LATEX_PRIME¶

LEFT_RIGHT_LATEX_PRIME¶

LEFT_CIRC¶

RIGHT_CIRC¶

LEFT_RIGHT_CIRC¶

The different arrow head types. These can be extended arbitrarily.

TikZStyle¶

class TikZStyle(custom_entries=None, *, width=None, height=None, x_scale=None, y_scale=None, scale=None, shift=None, bend_left=None, bend_right=None, loop=None, loop_above=None, loop_below=None, loop_left=None, loop_right=None, draw=True, circle=None, rectangle=None, dashed=None, dotted=None, line_width=None, shorten_start=None, shorten_end=None, color=None, fill=None, align=None, draw_opacity=None, fill_opacity=None)¶

TikZStyle holds information about what styles to apply to a TikZ object. This class implements a container, and the __getitem__() and __getattr__() methods. A style can be accessed in the following ways:

>>> scale_style = TikZStyle(x_scale="2cm")
>>> assert scale_style.x_scale == "2cm"
>>> assert scale_style["x_scale"] == "2cm"
>>> assert scale_style["x scale"] == "2cm"
>>> assert scale_style["x-scale"] == "2cm"
>>> assert scale_style.style["x scale"] == "2cm" # space is needed here! this use is discouraged

Additionally, some methods of this instance will ignore None values:

>>> draw_style = TikZStyle(draw=True)
>>> assert len(draw_style) == 1 # all other values are None
>>> assert "y_scale" not in draw_style
>>> assert "draw" in draw_style

One can either iterate over the non-None values of this instance, or call the to_tikz() method:

>>> multiple_style = TikZStyle(width="1cm", draw=True)
>>> for s in multiple_style:
...             print(s)
('width', '1cm')
('draw', True)
>>> print(multiple_style.to_tikz())
draw, width={1cm}

Style objects can be compared using == and !=, and test equal if and only if they have matching key value pairs in style (i.e. the values passed to the constructor).

>>> assert TikZStyle(dashed=True, line_width="2mm") == TikZStyle(dashed=True, line_width="2mm")
>>> assert TikZStyle(dashed=True) != EMPTY_STYLE

Style obejcts may also be combined using either +, &, or |, which all hold the same meaning. When styles are combined, the style obejct on the right will overwrite any overlapping attributes of the style on the left side.

>>> style1 = TikZStyle(dashed=True, align="left")
>>> style2 = TikZStyle(dotted=True, align="right")
>>> assert style1 + style2 == TikZStyle(dashed=True, dotted=True, align="right")
>>> assert style2 & style1 == TikZStyle(dashed=True, dotted=True, align="left")
>>> assert style1 | style2 == style1 + style2

Parameters: custom_entries (Optional[Mapping[AnyStr, DictVal]]) – an optional mapping of any entries not included in the keyword arguments

DictVal¶

The types of a dictionary entry of the styles dictionary.

alias of Optional[Union[AnyStr, bool, int, float]]

static normalize_key(s)¶

Removes any underscores or hyphens and replaces them with spaces.

property style: Dict[AnyStr, DictVal]¶

Returns: a copy of the styles stored in this instance

property colors: Tuple[SEPTeX.TikZBase.TikZColor]¶

Returns: a copy of the unique colors used in this instance, removes None values

property empty: bool¶

Returns: whether or not this style instance has no properties (aside from the draw flag) set

to_tikz()¶

Converts this object to a TikZ string.

TikZPicture¶

class TikZPicture(parent_env, style=TikZStyle(draw=True), defined_colors=(), indent_level=1)¶

TikZPicture represents the standard TikZ tikzpicture environment. This class aids in writing special TikZ objects like TikZColor, but can also be written to manually.

Warning

When a TikZNamed object is written to this class, its TikZNamed.definition string will be directly written to the document without registering it, or checking if the object has been written to this instance before. However, when a TikZDefinesWriteable object is written to this class, all the registered TikZNamed objects will be recursively written and registered, so that they can be reused without overwriting the old definitions. If one desires to redefine them anyway, one can write them directly to the instance manually or simply rename the objects to cause a new definition to be registered.

Note

Registered TikZNamed objects are implicitly inherited to TikZScope environments defined with this class as parent.

Parameters

parent_env (Union[LaTeXDocument, LaTeXEnvironment]) – the parent environment or document to this environment
style (TikZStyle) – the main style to use for this environment
defined_colors (Collection[TikZColor]) – any colors which have already been defined in the document and are accessible from within this environment, this option is useful if there are manually defined colors in the document
indent_level (int) – the number of tab characters to indent this environment relative to the parent environment

property written_named_object_definitions: Tuple[SEPTeX.TikZBase.TikZNamed]¶

Returns: the TikZNamed objects which have so far been written and defined by this environment

write_named_object_definition(*obj)¶

Register one or multiple TikZNamed objects with this instance. This will define the objects at the beginning of the environment using a special handler.

Parameters: obj (SEPTeX.TikZBase.TikZNamed) – the named object or objects to define

write(s)¶

Write s to the handler of this instance.

The following conditions apply to special object types:

If s is a string or TeXHandler this method will simply write it.

If s is a TikZWriteable object this method will first register the required packages, then the required TikZ libraries, then call the to_latex method of the object, and finally add ; to the end if it is missing.

If s is also a TikZNamed objet this method will additionally write its definition to the document directly. This is in contrast to how TikZDefinesWriteable works, since those objects will be defined with this class and then written to a special definition handler.

If s is also a TikZDefinesWriteable object this method will additionally register all the defined objects recursively, if they do not compare equal to any of the objects which have been defined by this class previously. These definitions are written to a special definition handler.

Parameters: s (Union[SEPTeX.TikZBase.TikZWriteable, AnyStr, SEPTeX.TeXBase.TeXHandler]) – the object to write to the handler

TikZScope¶

class TikZScope(parent_env, style=TikZStyle(draw=True), indent_level=1)¶

TikZScope represents the standard TikZ scope environment. It can only be instantiated with a parent environment inheriting from TikZPicture. This environment will automatically include all TikZNamed objects registered by the parent environment in its namespace.

Parameters

parent_env (TikZPicture) – the parent environment or document to this environment
style (TikZStyle) – the main style to use for this environment
indent_level (int) – the number of tab characters to indent this environment relative to the parent environment

Raises

TypeError – if the passed parent_env is not an instance of a TikZPicture class or subclass thereof