atform 0.2__py3-none-any.whl

atform/field.py

@@ -0,0 +1,142 @@
+# This module maintains user-defined form field configuration.
+
+
+from . import error
+from . import misc
+import collections
+
+
+# Object used to store the definition of each field.
+Field = collections.namedtuple(
+    "Field",
+    ["title", "length"],
+)
+
+
+# All defined fields, keyed by name, and ordered as added by add_field().
+fields = collections.OrderedDict()
+
+
+# Names identifying which fields will be applied to the next test.
+active_names = set()
+
+
+def validate_name_list(title, lst):
+    """Verifies a list to confirm it contains only valid field names."""
+    if not isinstance(lst, list):
+        raise error.UserScriptError(
+            f"Invalid {title} data type: {type(lst).__name__}",
+            f"{title} must be a list of field names.",
+        )
+    names = set()
+    for raw in lst:
+        name = misc.nonempty_string("field name", raw)
+        try:
+            fields[name]
+        except KeyError:
+            raise error.UserScriptError(
+                f"Undefined name in {title} list: {name}",
+                "Use a name defined with atform.add_field().",
+            )
+        names.add(name)
+    return names
+
+
+def get_active_names(include, exclude, active):
+    """Computes the resulting active names after applying filters."""
+    include = validate_name_list("include fields", include)
+    exclude = validate_name_list("exclude fields", exclude)
+    if active is not None:
+        return validate_name_list("active fields", active)
+    return active_names.union(include).difference(exclude)
+
+
+def get_active_fields(include, exclude, active):
+    """
+    Generates the list of field tuples to be applied to the next test
+    after applying filters.
+    """
+    names = list(get_active_names(include, exclude, active))
+
+    # Sort according to order defined by add_field().
+    names.sort(key=lambda n: list(fields.keys()).index(n))
+
+    return [fields[name] for name in names]
+
+
+################################################################################
+# Public API
+#
+# Items in this area are documented and exported for use by end users.
+################################################################################
+
+
+@error.exit_on_script_error
+@misc.setup_only
+def add_field(title, length, name, active=True):
+    """Adds a user entry field to capture test execution information.
+
+    Form fields are suitable for entering a single line of text at the beginning
+    of each test; fields will be listed in the order they were added.
+    This function can only be used in the setup area of the script,
+    before any tests or sections are created.
+
+    .. seealso:: :ref:`env_fields`
+
+    Args:
+        title (str): Text to serve as the field's prompt; must not be blank.
+        length (int): Maximum number of characters the field should be sized
+            to accommodate; must be greater than zero.
+        name (str): A tag used to identify this field; must be unique and
+            not blank.
+        active (bool, optional): Set to ``False`` if this field should not
+            be included in tests until explicitly activated at a later time,
+            such as with :py:func:`atform.set_active_fields`.
+    """
+    field = Field(
+        misc.nonempty_string("field title", title),
+        misc.validate_field_length(length),
+    )
+
+    name = misc.nonempty_string("field name", name)
+    try:
+        fields[name]
+    except KeyError:
+        fields[name] = field
+    else:
+        raise error.UserScriptError(
+            f"Duplicate field name: {name}",
+            "Select a unique field name."
+        )
+
+    if not isinstance(active, bool):
+        raise error.UserScriptError(
+            f"Invalid active selection: {active}",
+            "Set active to False, or omit the argument.",
+        )
+
+    if active:
+        active_names.add(name)
+
+
+@error.exit_on_script_error
+def set_active_fields(include=[], exclude=[], active=None):
+    """Alters the fields applied to each test created after this function.
+
+    May be called repeatedly to modify the fields applied to different
+    tests. The fields set by this function can also be overridden by
+    the ``include_fields``, ``exclude_fields``, and ``active_fields``
+    arguments of :py:class:`atform.Test`.
+
+    .. seealso:: :ref:`env_fields`
+
+    Args:
+        include (list[str], optional): Names of fields to add to later
+            tests.
+        exclude (list[str], optional): Names of fields to remove from
+            later tests.
+        active (list[str], optional): If provided, updates the fields
+            in later tests with this list.
+    """
+    global active_names
+    active_names = get_active_names(include, exclude, active)

atform/format.py

@@ -0,0 +1,146 @@
+# This module contains the text formatting API.
+
+
+from . import error
+import xml.etree.ElementTree as ElementTree
+
+
+# Mapping between typeface and font parameters of format_text() to
+# a (font, size) tuple used to populate intra-paragraph XML element
+# attributes. The size value is optional to adjust height relative to
+# normal text.
+FONTS = {
+    ("normal", "normal"): ("Times-Roman",),
+    ("normal", "bold"): ("Times-Bold",),
+    ("normal", "italic"): ("Times-Italic",),
+    ("monospace", "normal"): ("Courier", 14),
+    ("monospace", "bold"): ("Courier-Bold", 14),
+    ("monospace", "italic"): ("Courier-Oblique", 14),
+    ("sansserif", "normal"): ("Helvetica", 11),
+    ("sansserif", "bold"): ("Helvetica-Bold", 11),
+    ("sansserif", "italic"): ("Helvetica-Oblique", 11),
+}
+
+
+def allowed_format(i):
+    """
+    Formats a list of allowable format selectors into a string for use in
+    error messages.
+    """
+    uniq = set([f[i] for f in FONTS])
+    quoted = [f"'{s}'" for s in uniq]
+    quoted.sort()
+    return ", ".join(quoted[:-1]) + f", or {quoted[-1]}"
+
+
+################################################################################
+# Public API
+#
+# Items in this area are documented and exported for use by end users.
+################################################################################
+
+
+@error.exit_on_script_error
+def bullet_list(*items):
+    """Creates a list of items.
+
+    Items will be presented as an unnumbered list, in the same order they
+    appear in the function's parameters. This function may not be nested to
+    create nested lists.
+
+    .. seealso:: :ref:`format`
+
+    Args:
+        *items (str): The bullet list items. This is *not* a Python list of
+            items, but rather each item passed as a separate parameter.
+            E.g., ``"Item 1", "Item 2"``, not ``["Item 1", "Item 2"]``.
+
+    Returns:
+        str: The entire list with embedded formatting that can be incorporated
+        into strings passed to the ``objective``, ``equipment``,
+        ``preconditions``, and ``procedure`` parameters of
+        :py:class:`atform.Test`.
+    """
+    indent = 12 # Horizontal indentation in points applied to each item.
+
+    # The character used at the beginning of each item. Chosen to be distinct
+    # from the bullet used by ReportLab ListItem().
+    symbol = "♦"
+
+    stripped = []
+    for i in items:
+        try:
+            item = i.strip()
+        except AttributeError:
+            raise error.UserScriptError(
+                f"Invalid bullet list item type: {type(i).__name__}",
+                "Bullet list items must be strings.",
+            )
+        else:
+            stripped.append(item)
+
+    bullet_items = ["<bullet indent='{0}'>{1}</bullet>{2}".format(
+        indent,
+        symbol,
+        i,
+    ) for i in stripped]
+
+    # Add empty leading and trailing strings so items get surrounded by double
+    # newlines by the final join(), ensuring the list is separated from
+    # adjacent paragraphs.
+    bullet_items.insert(0, "")
+    bullet_items.append("")
+
+    return "\n\n".join(bullet_items)
+
+
+@error.exit_on_script_error
+def format_text(text, typeface="normal", font="normal"):
+    """Applies special formatting attributes to text.
+
+    The returned string can be incorporated into strings passed to the
+    ``objective``, ``equipment``, ``preconditions``, and ``procedure``
+    parameters of :py:class:`atform.Test`.
+
+    .. seealso:: :ref:`format`
+
+    Args:
+        text (str): The content to format.
+        typeface (str, optional): Typeface name: ``"monospace"`` or
+            ``"sansserif"``.
+        font (str, optional): Font style: ``"bold"`` or ``"italic"``.
+
+    Returns:
+        str: The original text with embedded formatting information.
+    """
+    if not isinstance(text, str):
+        raise error.UserScriptError(
+            f"Invalid formatted text type: {text}",
+            "Text to be formatted must be a string.",
+        )
+
+    typefaces = set([k[0] for k in FONTS.keys()])
+    if not typeface in typefaces:
+        raise error.UserScriptError(
+            f"Invalid text format typeface: {typeface}",
+            f"Select {allowed_format(0)} as a typeface.",
+        )
+
+    fonts = set([k[1] for k in FONTS.keys()])
+    if not font in fonts:
+        raise error.UserScriptError(
+            f"Invalid text format font: {font}",
+            f"Select {allowed_format(1)} as a font.",
+        )
+
+    font_values = FONTS[(typeface, font)]
+    attrib = {"face":font_values[0]}
+    try:
+        attrib["size"] = str(font_values[1])
+    except IndexError:
+        pass
+
+    # Enclose the string in a intra-paragraph XML markup element.
+    e = ElementTree.Element("font", attrib=attrib)
+    e.text = text
+    return ElementTree.tostring(e, encoding="unicode")

atform/id.py

@@ -0,0 +1,218 @@
+# This module manages the numeric identifiers assigned to each test.
+
+
+from . import error
+from . import misc
+import pathlib
+import tempfile
+
+
+# Fields assigned to the most recent test.
+current_id = [0]
+
+
+# Section titles, keyed by ID tuple.
+section_titles = {}
+
+
+def get_id():
+    """Returns the identifier to be used for the next test."""
+    global current_id
+    current_id[-1] = current_id[-1] + 1 # Increment last ID level for each test.
+
+    # Initialize section levels that have been reset(0) to one.
+    for i in range(0, len(current_id)):
+        if current_id[i] == 0:
+            current_id[i] = 1
+
+    return tuple(current_id)
+
+
+def to_string(id):
+    """Generates a presentation string for a given ID tuple."""
+    return ".".join([str(x) for x in id])
+
+
+def validate_section_title(title):
+    """Confirms a section title is valid.
+
+    Validation is implemented by attempting to create a folder named with
+    the title in a temporary directory.
+    """
+    if not isinstance(title, str):
+        raise error.UserScriptError(
+            f"Invalid section title data type: {type(title).__name__}",
+            "Section title must be a string.",
+        )
+
+    with tempfile.TemporaryDirectory() as tdir:
+        path = pathlib.Path(tdir, title)
+        try:
+            path.mkdir()
+        except OSError:
+            raise error.UserScriptError(
+                f"Invalid section title: '{title}'",
+                """
+                Use a section title that is also a valid file system
+                folder name.
+                """,
+            )
+
+
+################################################################################
+# Public API
+#
+# Items in this area are documented and exported for use by end users.
+################################################################################
+
+
+@error.exit_on_script_error
+def section(level, id=None, title=None):
+    """Creates a new section or subsection.
+
+    The target section level is incremented, and the new section can be given
+    an optional title. All subsections after the target level and individual
+    test numbers will be reset back to one.
+
+    .. seealso:: :ref:`section`
+
+    Args:
+        level (int): Target identifier level in which to start a new section;
+            must be greater than zero and less than the number of levels
+            configured with :py:func:`atform.set_id_depth` because the
+            highest level represents individual tests, not sections.
+        id (int, optional): Target section value; target section is incremented
+            by one if omitted. If specified, it must result in a jump
+            forward relative to the current section, i.e., jumping backwards,
+            or even to the current section, is not permitted.
+        title (str, optional): Section title; this information is only used
+            to name the folder where output PDFs for tests in
+            this section are generated, and consequently may only contain
+            characters allowed in file system folder names. If not provided,
+            the section folder name will just be the section number.
+    """
+    global current_id
+    global section_titles
+
+    if len(current_id) == 1:
+        raise error.UserScriptError(
+            "No section levels available",
+            """This function cannot be used unless the test ID depth is
+            first increased with atform.set_id_depth to allow tests to be
+            divided into sections."""
+        )
+
+    if not isinstance(level, int):
+        raise error.UserScriptError(
+            f"Invalid section level data type: {type(level).__name__}",
+            "Section level must be an integer.",
+        )
+
+    section_levels = range(1, len(current_id))
+    if not level in section_levels:
+        raise error.UserScriptError(
+            f"Invalid section level: {level}",
+            f"Use a section level between 1 and {section_levels[-1]}, "
+            "inclusive."
+        )
+
+    # Convert the one-based level to a zero-based index suitable for
+    # indexing current_id[].
+    id_index = level - 1
+
+    # Increment the target ID level.
+    if id is None:
+        current_id[id_index] = current_id[id_index] + 1
+
+    # Jump to a specific number.
+    else:
+        if not isinstance(id, int):
+            raise error.UserScriptError(
+                f"Invalid id data type: {type(id).__name__}",
+                "id must be an integer.",
+            )
+        elif id <= current_id[id_index]:
+            raise error.UserScriptError(
+                f"Invalid id value.",
+                f"Level {level} id must be greater than {current_id[id_index]}."
+            )
+        current_id[id_index] = id
+
+    # Reset higher ID levels.
+    for i in range(id_index + 1, len(current_id)):
+        current_id[i] = 0
+
+    if title is not None:
+        validate_section_title(title)
+        section = tuple(current_id[:id_index + 1])
+        stripped = title.strip()
+        if stripped:
+            section_titles[section] = stripped
+
+
+@error.exit_on_script_error
+@misc.setup_only
+def set_id_depth(levels):
+    """Configures the number of fields in test numeric identifiers.
+
+    For example, setting the depth to three will generate identifiers with
+    three numeric fields, like 2.1.1 or 4.2.3. This should be called once
+    before any tests or sections are created.
+
+    .. seealso:: :ref:`section`
+
+    Args:
+        levels (int): Number of identifier levels.
+    """
+    global current_id
+    if not isinstance(levels, int):
+        raise error.UserScriptError(
+            f"Invalid ID levels data type: {type(levels).__name__}",
+            "The number of ID levels must be an integer.",
+        )
+    if levels < 1:
+        raise error.UserScriptError(
+            f"Invalid identifier depth value: {levels}",
+            "Select an identifier depth greater than zero."
+        )
+    current_id = [0] * levels
+
+
+@error.exit_on_script_error
+def skip_test(id=None):
+    """Omits one or more tests.
+
+    This function can only skip tests within the current section, i.e.,
+    it will only affect the last identifier field. Typical usage is to
+    reserve a range of IDs or maintain numbering if a test is removed.
+
+    .. seealso:: :ref:`skip`
+
+    Args:
+        id (int, optional): ID of the next test. If omitted, one test will
+            be skipped.
+    """
+    global current_id
+
+    # Advance the test number normally without creating a test. This call
+    # also supports the skip-forward validation below by initializing
+    # any zero IDs to one.
+    get_id()
+
+    if id is not None:
+        if not isinstance(id, int):
+            raise error.UserScriptError(
+                f"Invalid id data type: {type(id).__name__}",
+                "id must be an integer.",
+            )
+        if id <= current_id[-1]:
+            raise error.UserScriptError(
+                f"Invalid id value: {id}",
+                f"Select an id greater than {current_id[-1]}."
+            )
+
+        # The current ID is set to one previous because the get_id() call
+        # above already increments the ID. The next test will then be assigned
+        # the given id value because get_id() increments before returning
+        # the assigned ID.
+        current_id[-1] = id - 1

atform/image.py

@@ -0,0 +1,121 @@
+# This module handles processing user-provided images.
+
+
+from . import error
+from . import misc
+import collections
+import io
+import PIL
+from reportlab.lib.units import inch
+from reportlab.platypus import Image
+
+
+# Data type for storing two-dimensional sizes.
+ImageSize = collections.namedtuple('ImageSize', ['width', 'height'])
+
+
+# Largest allowable logo image size, in inches.
+MAX_LOGO_SIZE = ImageSize(2.0, 1.5)
+
+
+# ReportLab Image object containing the user-specified logo.
+logo = None
+
+
+################################################################################
+# Public API
+#
+# Items in this area are documented and exported for use by end users.
+################################################################################
+
+
+@error.exit_on_script_error
+@misc.setup_only
+def add_logo(path):
+    """Selects an image file to be used as the logo.
+
+    The logo will appear on the first page of every test in the
+    upper-left corner.
+
+    The image must be a JPEG file with embedded metadata specifying DPI,
+    and may not exceed |max_logo_width| inches wide by |max_logo_height|
+    inches high. |project_name| will not scale or crop the image; the onus is
+    on the user to construct a logo suitable for presentation within
+    the allowable area.
+
+    .. seealso:: :ref:`setup`
+
+    Args:
+        path (str): Path to the image file.
+    """
+    global logo
+
+    if logo:
+        raise error.UserScriptError(
+            "Duplicate logo definition.",
+            """
+            atform.add_logo() can only be called once to define a single
+            logo image.
+            """,
+        )
+
+    # BytesIO are allowed to support unit testing.
+    if not isinstance(path, str) and not isinstance(path, io.BytesIO):
+        raise error.UserScriptError(
+            f"Invalid path data type: {type(path).__name__}",
+            "Path to the logo image file must be a string.",
+        )
+
+    try:
+        image = PIL.Image.open(path, formats=["JPEG"])
+    except FileNotFoundError:
+        raise error.UserScriptError(
+            f"Logo image file not found: {path}",
+        )
+    except PIL.UnidentifiedImageError:
+        raise error.UserScriptError(
+            f"Unsupported logo image format: {path}",
+            "Logo image file must be a JPEG.",
+        )
+    try:
+        dpi_raw = image.info["dpi"]
+    except KeyError:
+        raise error.UserScriptError(
+            "No DPI information found in logo image file.",
+            "Ensure the logo image file has embedded DPI metadata."
+        )
+
+    # Ensure DPI values are floats.
+    dpi = ImageSize(*[float(i) for i in dpi_raw])
+
+    size = ImageSize(
+        image.width / dpi.width,
+        image.height / dpi.height
+    )
+
+    if ((size.width > MAX_LOGO_SIZE.width)
+        or (size.height > MAX_LOGO_SIZE.height)):
+        raise error.UserScriptError(
+            f"""
+            Logo image is too large:
+            {size.width:.3} x {size.height:.3} (inch)""",
+            f"""
+            Reduce the logo image size to within {MAX_LOGO_SIZE.width} inch
+            wide and {MAX_LOGO_SIZE.height} inch high.
+            """,
+        )
+
+    # Dump the JPEG data to an in-memory buffer and convert to a Reportlab
+    # Image object.
+    buf = io.BytesIO()
+    image.save(
+        buf,
+        format="JPEG",
+        quality="keep",
+        dpi=dpi,
+    )
+    logo = Image(
+        buf,
+        width=size.width*inch,
+        height=size.height*inch,
+    )

atform/label.py

@@ -0,0 +1,72 @@
+# This module implements storage of IDs, such as a test number, referenced by
+# a user-provided label.
+
+
+from . import error
+import re
+import string
+
+
+# Target ids keyed by label.
+labels = {}
+
+
+# Regular expression pattern to match a valid label, which is based on
+# allowable identifiers for template strings.
+valid_label_pattern = re.compile(r"\w+$")
+
+
+def add(label, id):
+    """Assigns an identifier to a label.
+
+    This function is not exposed in the public API, however, the label
+    argument is passed directly from public API arguments, so it is
+    validated here. The id is generated internally by atform, e.g., a test
+    number, and can be assumed appropriate.
+    """
+    global labels
+
+    if not isinstance(label, str):
+        raise error.UserScriptError(
+            f"Invalid label data type: {label}",
+            "Label must be a string.",
+        )
+
+    if not valid_label_pattern.match(label):
+        raise error.UserScriptError(
+            f"Invalid label: {label}",
+            f"Labels may contain only letters, numbers, and underscore."
+        )
+
+    if label in labels:
+        raise error.UserScriptError(
+            f"Duplicate label: {label}",
+            "Select a label that has not yet been used.",
+        )
+
+    labels[label] = id
+
+
+def resolve(orig):
+    """Replaces label placeholders with the target IDs.
+
+    The public API already validates the original string to ensure it is
+    in fact a string, so only substitution needs to be checked.
+    """
+    tpl = string.Template(orig)
+
+    try:
+        return tpl.substitute(labels)
+
+    except KeyError as e:
+        raise error.UserScriptError(
+            f"Undefined label: {e}",
+            "Select a label that has been defined.",
+        )
+    except ValueError as e:
+        raise error.UserScriptError(
+            f"Invalid label replacement syntax.",
+            "Labels are formatted as $<name>, where <name> begins with a "
+            "letter or underscore, followed by zero or more letters, "
+            "numbers, or underscore.",
+        )