Skip to content

Commit

Permalink
rfctr: more modernization
Browse files Browse the repository at this point in the history
- Add type-annotations
- Blacken code (100-character line-length)
- Reformat docstrings to PEP257.
  • Loading branch information
scanny committed Sep 22, 2024
1 parent 5fe4026 commit 5cd2698
Show file tree
Hide file tree
Showing 28 changed files with 1,155 additions and 946 deletions.
12 changes: 6 additions & 6 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,8 @@
master_doc = "index"

# General information about the project.
project = u"opc-diag"
copyright = u"2013, Steve Canny"
project = "opc-diag"
copyright = "2013, Steve Canny"

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
Expand Down Expand Up @@ -196,7 +196,7 @@
# documentclass [howto/manual]
# ).
latex_documents = [
("index", "opc-diag.tex", u"opc-diag Documentation", u"Steve Canny", "manual"),
("index", "opc-diag.tex", "opc-diag Documentation", "Steve Canny", "manual"),
]

# The name of an image file (relative to this directory) to place at the top of
Expand Down Expand Up @@ -224,7 +224,7 @@

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [("index", "opc-diag", u"opc-diag Documentation", [u"Steve Canny"], 1)]
man_pages = [("index", "opc-diag", "opc-diag Documentation", ["Steve Canny"], 1)]

# If true, show URL addresses after external links.
# man_show_urls = False
Expand All @@ -239,8 +239,8 @@
(
"index",
"opc-diag",
u"opc-diag Documentation",
u"Steve Canny",
"opc-diag Documentation",
"Steve Canny",
"opc-diag",
"One line description of project.",
"Miscellaneous",
Expand Down
14 changes: 6 additions & 8 deletions docs/quickstart.rst
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,10 @@ into its parts and perhaps to put it back together again later. The ``extract``
subcommand provides the first half of this process, complemented by the
``repackage`` subcommand discussed next.

This is especially useful when you have a pretty good idea how some particular aspect of
the XML schema works but want to experiment with manual updates directly the the XML to
see what product behaviors those produce in, say, Microsoft Word or LibreOffice.

The command:

.. code-block:: bash
Expand All @@ -175,14 +179,8 @@ workbook will be found at ``example_dir/xl/workbook.xml`` and the thumbnail
image that may appear in a desktop icon for the file is found at
``example_dir/docProps/thumbnail.jpeg``.

Users on a \*nix operating system can accomplish much the same thing with the
command:

.. code-block:: bash
$ unzip example.xlsx -d example_dir
but I thought it might be handy from time to time to have it built into |opcd|.
Importantly, all the files are formatted for human readability. This is particularly
important when you plan to edit the XML by hand.


Use Case 5: ``repackage`` a package directory into a file
Expand Down
18 changes: 4 additions & 14 deletions features/environment.py
Original file line number Diff line number Diff line change
@@ -1,22 +1,12 @@
# -*- coding: utf-8 -*-
#
# environment.py
#
# Copyright (C) 2013 Steve Canny [email protected]
#
# This module is part of python-opc and is released under the MIT License:
# http://www.opensource.org/licenses/mit-license.php

"""
Used by behave to set testing environment before and after running acceptance
tests.
"""
"""Used by behave to set testing environment before and after running acceptance tests."""

import os

from behave.runner import Context

scratch_dir = os.path.abspath(os.path.join(os.path.split(__file__)[0], "_scratch"))


def before_all(context):
def before_all(context: Context):
if not os.path.isdir(scratch_dir):
os.mkdir(scratch_dir)
78 changes: 29 additions & 49 deletions features/steps/helpers.py
Original file line number Diff line number Diff line change
@@ -1,32 +1,25 @@
# -*- coding: utf-8 -*-
#
# helpers.py
#
# Copyright (C) 2012, 2013 Steve Canny [email protected]
#
# This module is part of opc-diag and is released under the MIT License:
# http://www.opensource.org/licenses/mit-license.php

"""Acceptance test helpers."""

from __future__ import unicode_literals
# pyright: reportPrivateUsage=false

from __future__ import annotations

import os
import subprocess

from step_data import Manifest
from step_data import Manifest, _Manifest


def absjoin(*paths):
def absjoin(*paths: str):
return os.path.abspath(os.path.join(*paths))


def ref_pkg_path(filename):
def ref_pkg_path(filename: str):
ref_pkg_dir = absjoin(test_file_dir, "reference_pkgs")
return os.path.relpath(absjoin(ref_pkg_dir, filename))


def scratch_path(name):
def scratch_path(name: str):
return os.path.relpath(absjoin(scratch_dir, name))


Expand All @@ -35,35 +28,29 @@ def scratch_path(name):
test_file_dir = absjoin(thisdir, "../test_files")


def assertManifestsMatch(manifest1, manifest2, name1, name2):
"""
Raise |AssertionError| if *manifest1* does not exactly match *manifest2*.
*name1* and *name2* appear in the diff printed if the assertion fails.
def assertManifestsMatch(manifest1: _Manifest, manifest2: _Manifest, name1: str, name2: str):
"""Raise |AssertionError| if `manifest1` does not exactly match `manifest2`.
`name1` and `name2` appear in the diff printed if the assertion fails.
"""
msg = "Package manifests don't match\n\n%s" % manifest1.diff(
manifest2, name1, name2
)
msg = "Package manifests don't match\n\n%s" % manifest1.diff(manifest2, name1, name2)
assert manifest1 == manifest2, msg


def assertPackagesMatch(path1, path2):
"""
Raise |AssertionError| if manifest of package at *path1* does not exactly
match that of package at *path2*.
def assertPackagesMatch(path1: str, path2: str):
"""Raise if manifest of package at `path1` does not exactly match that of package at `path2`.
Raises `AssertionError` in that case.
"""
manifest1, manifest2 = Manifest(path1), Manifest(path2)
msg = "Package manifests don't match\n\n%s" % manifest1.diff(
manifest2, path1, path2
)
msg = "Package manifests don't match\n\n%s" % manifest1.diff(manifest2, path1, path2)
assert manifest1 == manifest2, msg


class OpcCommand(object):
"""
Executes opc-diag command as configured and makes results available.
"""
class OpcCommand:
"""Executes opc-diag command as configured and makes results available."""

def __init__(self, subcommand, *args):
def __init__(self, subcommand: str, *args: str):
self.subcommand = subcommand
self.args = args

Expand All @@ -83,11 +70,11 @@ def assert_stdout_empty(self):
tmpl = "Unexpected output on stdout\n'%s'\n"
assert self.std_out == "", tmpl % self.std_out

def assert_stdout_matches(self, filename):
"""
Raise AssertionError with helpful diagnostic message if output
captured on stdout doesn't match contents of file identified by
*filename* in known directory.
def assert_stdout_matches(self, filename: str):
"""Raise if captured stdout does not match contents of `filename`.
Raise AssertionError with helpful diagnostic message if output captured on stdout doesn't
match contents of file identified by `filename` in known directory.
"""
expected_stdout = self._expected_output(filename)
msg = "\n\nexpected output:\n'%s'\n\nactual output:\n'%s'" % (
Expand All @@ -98,26 +85,19 @@ def assert_stdout_matches(self, filename):
assert std_out == expected_stdout, msg

def execute(self):
"""
Execute the configured command in a subprocess and capture the
results.
"""
"""Execute the configured command in a subprocess and capture the results."""
args = ["python", "opc-stub"]
args.append(self.subcommand)
args.extend(self.args)
self.proc = subprocess.Popen(
args, stdout=subprocess.PIPE, stderr=subprocess.PIPE
)
self.proc = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
std_out_bytes, std_err_bytes = self.proc.communicate()
self.std_out = std_out_bytes.decode("utf-8")
self.std_err = std_err_bytes.decode("utf-8")
return self

@staticmethod
def _expected_output(filename):
"""
Return contents of file with *filename* in known directory as text.
"""
def _expected_output(filename: str):
"""Return contents of file with `filename` in known directory as text."""
path = absjoin(test_file_dir, "expected_output", filename)
with open(path, "rb") as f:
expected_bytes = f.read()
Expand Down
Loading

0 comments on commit 5cd2698

Please sign in to comment.