opensuse / pytest-xmlcomp Goto Github PK

Problem

The url keyword points to the wrong GitHub project in the setup.py file.

Solution

Use https://github.com/openSUSE/pytest-xmlcomp in setup.py

Problem

Missing quotes in https://github.com/openSUSE/pytest-xmlcomp/blob/master/setup.py#L42

Solution

Put quotes around it. 😉

Problem

In the README.rst file, the Travis link goes to the master branch. It should go to the develop branch

Solution

master -> develop

(quite easy 😉 )

Problem

The JSON file contains an XPath expression and a list of possible results, for example:

["/d:doc",     ["<doc>"]]

However, namespaced result are currently undefined, for example, an element which belongs to a namespace.

Solution

The following solutions assume, we have an element doc in the namespace urn:x-example:ns with the prefix d.

1. Use the Clark notation in the result
   <{urn:x-example:ns}doc>
   Pros: It's obvious
   Cons: Long, incorrect XML notation

2. Use a prefix
   <d:doc>
   Pro: Easy to read, correct XML syntax
   Cons: Maybe not always obvious which namespace it belongs to.

Possible file: pytest_xmlcomp/plugin.py, function stringifylist.

Problem

when using a wrongly XML or JSON file for this plugin, the plugin fails.

Solution

The plugin should either

• report the affected files, or
• catch the syntax error and report the skipped file(s).

Maybe you can use:

• pytest.fail()
• pytest.skip()

Problem

When issue #2 is done, initialize repo to work with GitFlow.

Solution

Run git flow init -d inside master branch and push to develop.

Problem

The documentation needs some updates.

Solution

Correct the following in the README.rst file:

• Fix the Travis URL, should go to "openSUSE" not "Lightlace". 😉
• Remove Appveyor, we don't need that
• Fill in the "Requirements" section
• Mention somewhere, that this project adheres to the Semantic Versioning Specification

The other sections ("Features", "Usage") are fixed in other pull requests once we know better what we want. 😉

Problem

In order to test stuff, we need to add a .travis.yml file.

Solution

A simple .travis.yml file could look like this (see Travis documentation for more information):

language: python
sudo: false
env:
  global:
    - LD_PRELOAD=/lib/x86_64-linux-gnu/libSegFault.so
    - SEGFAULT_SIGNALS=all

matrix:
  include:
    - env: TOXENV=flake8
    - env: TOXENV=3.4
      python: 3.4
    - env: TOXENV=3.5
      python: 3.5
    - env: TOXENV=3.6
      python: 3.6

before_install:
  - python3 --version
  - uname -a
  - lsb_release -a
  - virtualenv --version
  - easy_install --version
  - pip --version
  - tox --version

install:
  # - pip install -U pip setuptools
  - pip install -r dev-requirements.pip

script:
    - tox -v

before_cache:
  - rm -rf $HOME/.cache/pip/log

cache:
  directories:
    - $HOME/.cache/pip

notifications:
  email:
    on_success: never
    on_failure: always

Problem

The MANIFEST.in file manages what files or directories are added to the distribution file (when you run setup.py sdist you get a tarball dists/pytest-xmlcomp-VERSION.tar.gz).
Currently, some files and directories are missing which should be clearly added.

Solution

Make the following additions:

• Add all *.rst files
• Add all *.pip files
• Add tox.ini
• Add the directory and all files from docs/
• Add the directory and all files from tests/
• check with check-manifest

For details, see https://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template

Problem

Currently, there is no documentation

Solution

Add the following topics into the documentation

• installing the pytest-xmlcomp plugin
• using the plugin
• generating XPath expressions in JSON files
  • link to http://json.org
  • validate your JSON files with: python3 -m json.tool foo.json
• documenting hooks

Problem

The plugin comes with options (currently one) which is not documented in the README.rst file.

Solution

Add an additional section about options

Problem

The bumpversion tool needs a configuration file.

Solution

See https://pypi.org/project/bumpversion/#configuration

• add version string in pytest_xmlcomp.py, for example __version__ = "0.1.0"
• add version string in documentation, file docs/index.rst
• add version string in README.rst
• add .bumpversion.cfg and add pointers to all files with version information

According to the link above, the content can also be integrated into a setup.cfg, so a dedicated file is not really necessary. It's a matter of taste.

See issue #19.

Problem

Currently, the tox.ini configuration file requires pytest>=3.0. However, we need to use our requirement file.

Solution

index 07d5d28..5f34e04 100644
--- i/tox.ini
+++ w/tox.ini
@@ -3,7 +3,7 @@
 envlist = py34,py35,py36,pypy,flake8
 
 [testenv]
-deps = pytest>=3.0
+deps = -r requirements.pip
 commands = pytest {posargs:tests}

Problem

the current design in our JSON file doesn't include any namespace definitions.

Solution

Maybe add another section which contains the namespaces and the prefixes. These prefixes can be used in the consecutive XPath expression.

One solution could be:

[
  [["d", "http://docbook.org/ns/docbook"],
   ["xi", "http://www.w3.org/2001/XInclude"],
   ["xlink", "http://www.w3.org/1999/xlink"]
  ],
  ["/d:doc",     ["<doc>"]],
  ["/d:doc/foo", ["<foo>"]]
]

Problem

The documentation needs Sphinx to build. As such, we should provide a requirement file for documentation too.

Solution

Add a requirements.pip file inside the docs folder with the following content:

Sphinx

We should also decide on a theme of the documentation, maybe provided as a different module (which has to be inserted as well).

Problem

The hook should clearly define its purpose:

• The naming of our hook should be improved (add the name of our plugin to it)
• Is the only parameter (XML file) enough? Maybe the user wants to access some other objects?

Solution/Idea

• rename it from pytest_transform_xml to pytest_xmlcomp_transform_xml?
• Maybe add another argument config? That way the user has access to the configuration file and its values and can influence some parameters for the XML parser.

Problem

Our project needs to create a setup.cfg to collect all helpful configuration options.

Solution

The setup.cfg is an INI file and collects several options for different tools into sections.

[bdist_wheel]
# This flag says to generate wheels that support both Python 2 and Python
# 3. If your code will not run unchanged on both Python 2 and 3, you will
# need to generate separate wheels for each Python version that you
# support.
universal=1

[tool:pytest]
# add special options for pytest

[flake8]
# add special options for flake8
exclude =.env/*,.tmp/*

[pycodestyle]
# maybe we should add this section as well (not sure)

Problem

The directory .pytest_cache/ needs to be ignored.

Solution

Add .pytest_cache/ in .gitignore

Problem

To have a good overview and to help with releases, the project needs a Changelog.

Solution

Create a file CHANGELOG.rst. The content could look like this:

Changelog
=========

0.2.0 (2018-04-24)
---------------------------------

# Add here your list of bugfixes

0.1.0 (2018-04-23)
---------------------------------

* Create initial project