Commit eb26a665 authored by Etienne Nadji's avatar Etienne Nadji
Browse files

Code documentation and annotations

	modifié :         colors.py
	modifié :         common/math.py
	modifié :         common/xml.py
	modifié :         dimensions.py
	modifié :         document.py
	modifié :         exceptions.py
	modifié :         itemattribute.py
	modifié :         marks.py
	modifié :         pageobjects.py
	modifié :         pages.py
	modifié :         patterns.py
	modifié :         sla.py
	modifié :         stories.py
parent 04b8aed9
......@@ -107,7 +107,7 @@ class Color(xmlc.PyScribusElement):
#--- Color management --------------------------------------
def set_space_colors(self, space, colors):
def set_space_colors(self, space: str, colors: list):
"""
Set color space and color inks of the colors.
......@@ -133,7 +133,13 @@ class Color(xmlc.PyScribusElement):
if spaced:
self.set_colors(colors)
def set_colors(self, colors, space=False):
def set_colors(self, colors: list, space=False):
"""
:type colors: list
:param colors: List of inks values (float).
:type space: string
:param space: Optionnal. Color space. Either "cmyk" or "rgb".
"""
if not space:
if self.is_cmyk:
......@@ -182,7 +188,7 @@ class Color(xmlc.PyScribusElement):
return False
def set_space(self, space):
def set_space(self, space: str):
"""
Set the color space (CMYK / RGB) of the color.
......@@ -205,7 +211,7 @@ class Color(xmlc.PyScribusElement):
#--- PyScribus standard methods ----------------------------
def fromdefault(self, default="Black"):
def fromdefault(self, default: str = "Black"):
if default in self.pyscribus_defaults:
......@@ -223,9 +229,9 @@ class Color(xmlc.PyScribusElement):
return False
def fromxml(self, xml):
def fromxml(self, xml: ET._Element):
"""
:type xml: lxml._Element
:type xml: lxml.etree._Element
:param xml: XML source of color
:rtype: boolean
:returns: True if XML parsing succeed
......@@ -280,7 +286,7 @@ class Color(xmlc.PyScribusElement):
def toxml(self):
"""
:rtype: lxml._Element
:rtype: lxml.etree._Element
:returns: Color as XML element
"""
......@@ -436,7 +442,7 @@ class GradientColorStop(xmlc.PyScribusElement):
return True
def _quick_setup(self, settings):
def _quick_setup(self, settings: dict):
"""
Method for defining gradient stop settings from class
instanciation kwargs.
......@@ -472,7 +478,7 @@ class GradientColorStop(xmlc.PyScribusElement):
self.opacity = dimensions.Dim(100, "pc")
self.position = dimensions.Dim(0, "pcdecim")
def fromxml(self, xml):
def fromxml(self, xml: ET._Element):
if xml.tag == "CSTOP":
if (color := xml.get("NAME")) is not None:
self.color = color
......
......@@ -48,9 +48,9 @@ class FloatEnum(enum.Enum):
# Fonctions =============================================================#
def necessary_float(f):
def necessary_float(f: float):
"""
Return integer if float f has no decimals.
Return **integer** if float f has no decimals, else returns **float**.
:type f: float
:param f: Float value
......@@ -66,6 +66,9 @@ def necessary_float(f):
def mm(milimeters):
"""
Returns milimeters in pica points.
:type milimeters: int,float
:param milimeters: Milimeters
"""
return float(milimeters) / PICA_TO_MM
......
......@@ -77,7 +77,7 @@ class PyScribusElement:
#--- Quick setup ---------------------------------
def _quick_setup(self, settings):
def _quick_setup(self, settings: dict):
"""
Method for defining style settings from class
instanciation kwargs.
......@@ -151,15 +151,15 @@ class PyScribusElement:
def toxml(self):
"""
:rtype: lxml._Element
:rtype: lxml.etree._Element
:returns: SLA element as LXML ElementTree element
"""
return False
def fromxml(self, xml):
def fromxml(self, xml: ET._Element):
"""
:type xml: lxml._Element
:type xml: lxml.etree._Element
:param xml: Some XML element
:rtype: boolean
:returns: True if XML parsing succeed
......@@ -198,15 +198,17 @@ class OrphanElement(PyScribusElement):
:ivar string tag: XML tag
"""
def __init__(self, tag):
def __init__(self, tag: str):
PyScribusElement.__init__(self)
self.tag = tag
def toxml(self):
"""
:rtype: lxml._Element
:rtype: lxml.etree._Element
"""
xml = ET.Element(self.tag)
return xml
def fromdefault(self):
......@@ -215,15 +217,16 @@ class OrphanElement(PyScribusElement):
# a default.
return True
def fromxml(self, xml):
def fromxml(self, xml: ET._Element):
"""
Parse XML element with tag OrphanElement.tag
:type xml: lxml.etree._Element
:param xml: XML element
:type xml: lxml._Element
:rtype: bool
:returns: bool
"""
if xml.tag == self.tag:
return True
......@@ -234,18 +237,27 @@ class OrphanElement(PyScribusElement):
# Fonctions =============================================================#
# NOTE
# We need a better typology of functions here :
#
# +---------------------+------------------+---------+---------------------------------+-----------+
# | Function name | New name ? | Returns | Manipulation | Side |
# +---------------------+------------------+---------+---------------------------------+-----------+
# | float_or_int_string | out_cleanfloat | string | number without useless decimals | xml |
# | str_or_nonestr | out_str_nonestr | string | string or "None" | xml ? |
# | bool_to_num | out_num_boolean | string | boolean as "0" or "1" | xml |
# | num_to_bool | in_num_boolean | boolean | "0" or "1" as boolean | pyscribus |
# | bool_or_else_to_num | out_zero_string | string | "0" if not(v) or v | xml |
# | none_or_str | out_empty_string | string | "" if v is None or v | xml ? |
# +---------------------+------------------+---------+---------------------------------+-----------+
# +---------------------+------------------+---------+------------------------+-----------+
# | Function name | New name ? | Returns | Manipulation | Side |
# +=====================+==================+=========+========================+===========+
# | float_or_int_string | out_cleanfloat | string | number without useless | ps -> xml |
# | | | | decimals | |
# +---------------------+------------------+---------+------------------------+-----------+
# | str_or_nonestr | out_str_nonestr | string | string or "None" | ps -> xml |
# +---------------------+------------------+---------+------------------------+-----------+
# | bool_to_num | out_num_boolean | string | boolean as "0" or "1" | ps -> xml |
# +---------------------+------------------+---------+------------------------+-----------+
# | bool_or_else_to_num | out_zero_string | string | "0" if not(v) or v | ps -> xml |
# +---------------------+------------------+---------+------------------------+-----------+
# | none_or_str | out_empty_string | string | "" if v is None or v | ps -> xml |
# +---------------------+------------------+---------+------------------------+-----------+
# | num_to_bool | in_num_boolean | boolean | "0" or "1" as boolean | xml -> ps |
# +---------------------+------------------+---------+------------------------+-----------+
# From PyScribus to XML ========================================#
def float_or_int_string(f):
......@@ -254,7 +266,7 @@ def float_or_int_string(f):
else:
return str(f)
def str_or_nonestr(v):
def str_or_nonestr(v: str):
"""
Returns v if v is a non-empty string, else returns 'None'.
......@@ -266,7 +278,7 @@ def str_or_nonestr(v):
else:
return "None"
def bool_to_num(b):
def bool_to_num(b: bool):
"""
Returns '1' if b is true, returns '0' if b is false.
......@@ -278,18 +290,6 @@ def bool_to_num(b):
else:
return "0"
def num_to_bool(n):
"""
Return True if n == '1', else returns False.
:rtype: bool
"""
if n == "1":
return True
else:
return False
def bool_or_else_to_num(b):
"""
Returns '0' if b is False, else return b as string.
......@@ -308,12 +308,29 @@ def none_or_str(v):
:rtype: str
"""
if v is None:
return ""
else:
return str(v)
def undocumented_to_python(xml, attributes):
# From XML to PyScribus ========================================#
def num_to_bool(n: str):
"""
Return True if n == '1', else returns False.
:rtype: bool
"""
if n == "1":
return True
else:
return False
# Undocumented attributes ======================================#
def undocumented_to_python(xml: ET._Element, attributes: list):
"""
Function to manage the import of undocumented
XML/SLA attributes.
......@@ -321,19 +338,20 @@ def undocumented_to_python(xml, attributes):
Used in PyScribus fromxml() methods until there is
no attribute undocumented and handled.
:type xml: lxml.etree._Element
:param xml: XML element
:type xml: lxml._Element
:param attributes: List of attributes' names
:type attributes: list
:param attributes: List of attributes' names
:returns: Dictionnary with attributes names as
keys and attribute values as values.
:rtype: dict
Use lxml._Element.get() to get attributes values,
Use lxml.etree._Element.get() to get attributes values,
so missing attributes will have None as a value.
.. seealso:: `undocumented_to_xml()`
"""
undocumented = {}
for att_name in attributes:
......@@ -341,7 +359,8 @@ def undocumented_to_python(xml, attributes):
return undocumented
def undocumented_to_xml(xml, undocumented, no_none=False):
def undocumented_to_xml(
xml: ET._Element, undocumented: dict, no_none: bool = False):
"""
Function to manage the export of undocumented
XML/SLA attributes.
......@@ -349,13 +368,15 @@ def undocumented_to_xml(xml, undocumented, no_none=False):
Used in PyScribus toxml() methods until there is
no attribute undocumented and handled.
:type xml: lxml.etree._Element
:param xml: XML element
:type xml: lxml._Element
:type undocumented: dict
:param undocumented: Dictionnary of XML attributes.
Return of undocumented_to_python()
:type undocumented: dict
:type no_none: bool
:param no_none: Skips attribute if its value is None
:returns: xml
:rtype: lxml._Element
:rtype: lxml.etree._Element
Add attributes to a XML element using undocumented
dictionnary keys as XML attributes' names and
......@@ -376,7 +397,7 @@ def undocumented_to_xml(xml, undocumented, no_none=False):
return xml
def all_undocumented_to_python(xml):
def all_undocumented_to_python(xml: ET._Element):
"""
Function to manage the import of undocumented
XML/SLA attributes.
......@@ -387,10 +408,8 @@ def all_undocumented_to_python(xml):
Used instead of undocumented_to_python() if there
is no defined list of undocumented attributes.
:type xml: lxml.etree._Element
:param xml: XML element
:type xml: lxml._Element
:param attributes: List of attributes' names
:type attributes: list
:returns: Dictionnary with attributes names as
keys and attribute values as values.
:rtype: dict
......@@ -402,6 +421,7 @@ def all_undocumented_to_python(xml):
.. seealso:: all_undocumented_to_xml()
"""
undocumented = {}
for att_name, att_value in xml.attrib.items():
......@@ -409,7 +429,9 @@ def all_undocumented_to_python(xml):
return undocumented
def all_undocumented_to_xml(xml, undocumented, report=True, msg=""):
def all_undocumented_to_xml(
xml: ET._Element, undocumented: dict,
report: bool = True, msg: str = ""):
"""
Function to manage the export of undocumented
XML/SLA attributes.
......@@ -417,11 +439,16 @@ def all_undocumented_to_xml(xml, undocumented, report=True, msg=""):
Used in PyScribus toxml() methods until there is
no attribute undocumented and handled.
:type xml: lxml.etree._Element
:param xml: XML element
:type xml: lxml._Element
:type undocumented: dict
:param undocumented: Dictionnary of XML attributes.
Return of all_undocumented_to_python()
:type undocumented: dict
:type report: bool
:param report: Print all undocumented attributes found in xml element.
:type msg: str
:param msg: Human readable name for the xml element when report parameter
is True.
:returns: List containing LXML element and undocumented attributes
names list.
:rtype: list
......
......@@ -91,7 +91,9 @@ class Dim:
"sec": ["s", "sec"]
}
def __init__(self, value, unit="pica", is_int=False, original_unit=False):
def __init__(
self, value, unit: str = "pica", is_int: bool = False,
original_unit: bool = False):
self.is_int = False
if is_int:
......@@ -180,7 +182,7 @@ class Dim:
return True
def set_unit(self, unit="pica"):
def set_unit(self, unit: str = "pica"):
"""
Set the unit used.
......@@ -232,7 +234,7 @@ class Dim:
#--- XML export ------------------------------------------------------
def toxmlstr(self, no_useless_decimals=False):
def toxmlstr(self, no_useless_decimals: bool = False):
"""
Returns a XML string of the dimension according to its unit.
......@@ -284,7 +286,7 @@ class Dim:
#--- Conversion into other units -------------------------------------
def _ceil(self, value, ceil=False):
def _ceil(self, value, ceil: bool = False):
"""
Ceil value if ceil is True.
......@@ -301,7 +303,7 @@ class Dim:
else:
return value
def _convertorval(self, obj, value, unit):
def _convertorval(self, obj, value, unit: str):
"""
Returns a Dim object with unit <unit> if <obj>, or <value>.
......@@ -325,7 +327,7 @@ class Dim:
return True
def topica(self, ceil=False, obj=False):
def topica(self, ceil: bool = False, obj: bool = False):
"""
Returns the value of Dim in pica point unit.
Raise ValueError if Dim is not convertable
......@@ -351,7 +353,7 @@ class Dim:
obj, self._ceil(self.value / Dim.PICA_TO_MM, ceil), "pica"
)
def todpi(self, ceil=False, obj=False):
def todpi(self, ceil: bool = False, obj: bool = False):
"""
Returns the value of Dim in DPI unit.
Raise ValueError if Dim is not convertable
......@@ -371,7 +373,7 @@ class Dim:
"Can't convert that into DPI"
)
def topc(self, ceil, obj=False):
def topc(self, ceil: bool, obj: bool = False):
"""
Returns the value of Dim as integer percentage.
Raise ValueError if Dim is not convertable
......@@ -391,7 +393,7 @@ class Dim:
"Can't convert that into percentage"
)
def tolpi(self, ceil=False, obj=False):
def tolpi(self, ceil: bool = False, obj: bool = False):
"""
Returns the value of Dim in LPI unit.
Raise ValueError if Dim is not convertable
......@@ -411,7 +413,7 @@ class Dim:
"Can't convert that into LPI"
)
def tomm(self, ceil=False, obj=False):
def tomm(self, ceil: bool = False, obj: bool = False):
"""
Returns the value of Dim in milimeter unit.
......@@ -438,7 +440,7 @@ class Dim:
#--- Defaults --------------------------------------------------------
def fromdefault(self, default):
def fromdefault(self, default: str):
"""
Set Dim attributes according to a named default.
......@@ -614,7 +616,7 @@ class DimBox:
#--- Shorthands for corners coordinates ------------------------------
def _setxy(self, corner, value, xy, rotated=False):
def _setxy(self, corner, value, xy, rotated: bool = False):
if corner.lower() in [
"top-left", "top-right",
"bottom-left", "bottom-right"]:
......@@ -634,7 +636,7 @@ class DimBox:
else:
raise KeyError()
def _getxy(self, corner, xy, rotated=False):
def _getxy(self, corner, xy, rotated: bool = False):
if corner.lower() in [
"top-left", "top-right",
"bottom-left", "bottom-right"]:
......@@ -651,21 +653,21 @@ class DimBox:
else:
raise KeyError()
def setx(self, corner, value, rotated=False):
def setx(self, corner, value, rotated: bool = False):
return self._setxy(corner, value, "x", rotated)
def sety(self, corner, value, rotated=False):
def sety(self, corner, value, rotated: bool = False):
return self._setxy(corner, value, "y", rotated)
def getx(self, corner, rotated=False):
def getx(self, corner, rotated: bool = False):
return self._getxy(corner, "x", rotated)
def gety(self, corner, rotated=False):
def gety(self, corner, rotated: bool = False):
return self._getxy(corner, "y", rotated)
#--- Box modification ------------------------------------------------
def move(self, posx=0, posy=0, refpoint="top-left"):
def move(self, posx: float = 0, posy: float = 0, refpoint: str = "top-left"):
"""
Move the box at posx, posy position.
......@@ -705,7 +707,9 @@ class DimBox:
return False
def translate(self, amountx=0, amounty=0, refpoint="top-left"):
def translate(
self, amountx: float = 0, amounty: float = 0,
refpoint: str = "top-left"):
"""
Move the box by an amount of amountx, amounty
......@@ -935,7 +939,7 @@ class DimBox:
else:
return False
def resize_side(self, side, value):
def resize_side(self, side: str, value: float):
"""
Resize the box from a side.
......@@ -978,7 +982,7 @@ class DimBox:
else:
return False
def rotate(self, degree):
def rotate(self, degree: float):
"""
Rotate the box by degree.
......
......@@ -667,8 +667,9 @@ class Document(PyScribusElement):
#========================================================================
def fromxml(self, xml):
def fromxml(self, xml: ET._Element):
# --- DOCUMENT attributes ----------------------------------------
# TODO DOCUMENT many attribs…
# Metadatas
......@@ -917,7 +918,7 @@ class Document(PyScribusElement):
return True
def toxml(self, optional=True):
def toxml(self, optional: bool = True):
xml = ET.Element("DOCUMENT")
# --- DOCUMENT attributes ----------------------------------------
......@@ -1160,7 +1161,17 @@ class Document(PyScribusElement):
#========================================================================
def pageobjects(self, object_type=False, templatable=False):
def pageobjects(self, object_type=False, templatable: bool = False):
"""
Return document page objets.
:type object_type: string,bool
:param object_type: Page object type to filter, or do not filter at all.
See pageobjects.po_type_classes for valid values.
:type templatable: bool
:param templatable: Only return templatable page objects.
"""
pos_ret = []
# If there is a object type filter, we filter before checking
......@@ -1578,7 +1589,7 @@ class Profile(PyScribusElement):
else:
return False
def fromxml(self, xml):
def fromxml(self, xml: ET._Element):
name = xml.get("Name")
if name is not None:
......@@ -1609,7 +1620,7 @@ class Profile(PyScribusElement):
return True
def fromdefault(self, name):
def fromdefault(self, name: str):
"""
"""
......@@ -1796,7 +1807,7 @@ class Layer(PyScribusElement):
self.flow = True
self.selectable = False
def fromxml(self, xml):
def fromxml(self, xml: ET._Element):
number = xml.get("NUMMER")
if number is not None:
......
......@@ -58,9 +58,9 @@ class ConflictingLayer(Exception):
class UnknownOrEmptyItemAttributeType(Exception):
"""
Exception raised when a itemattribute.ItemAttribute (and inherited
Exception raised when a ``itemattribute.ItemAttribute`` (and inherited
classes) has a unknown or empty type, as it is not in
itemattribute.ItemAttribute.attrib_types
``itemattribute.ItemAttribute.attrib_types``
"""
pass
......@@ -85,8 +85,8 @@ class InvalidColor(Exception):
Exception raised when color inks (CMYK or RGB) are invalid, incomplete
or doesn't even exists.
RGB inks must range from 0 to 255.
CMYK inks must range from 0 to 100.
- RGB inks must range from 0 to 255.
- CMYK inks must range from 0 to 100.
"""
pass
......@@ -105,18 +105,20 @@ class UnknownDimUnit(Exception):