From 6a32f48741a1a3989ba541e29ba7151d89b1ad27 Mon Sep 17 00:00:00 2001 From: Joohwan Oh Date: Thu, 9 Nov 2017 01:55:04 -0800 Subject: [PATCH] Add contributing page to the documentation --- .travis.yml | 2 +- README.rst | 9 ++++ docs/conf.py | 6 +-- docs/contributing.rst | 114 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 3 +- docs/overview.rst | 2 +- kq/cli.py | 2 +- kq/version.py | 2 +- kq/worker.py | 3 +- tests/test_queue.py | 3 +- tests/test_worker.py | 2 +- 11 files changed, 136 insertions(+), 12 deletions(-) create mode 100644 docs/contributing.rst diff --git a/.travis.yml b/.travis.yml index e10f174..66bcaaa 100644 --- a/.travis.yml +++ b/.travis.yml @@ -12,6 +12,6 @@ install: - pip install python-coveralls - python setup.py install script: - - py.test --cov-report= --cov=kq tests/ + - py.test --cov=kq after_success: - coveralls \ No newline at end of file diff --git a/README.rst b/README.rst index ad428ae..cbc82c5 100644 --- a/README.rst +++ b/README.rst @@ -129,6 +129,15 @@ You may need to use ``sudo`` depending on your environment setup. .. _GitHub: https://github.com/joowani/kq +Contributing +============ + +Please have a look at this page_ before submitting a pull request. Thanks! + +.. _page: + http://kq.readthedocs.io/en/master/contributing.html + + Credits ======= diff --git a/docs/conf.py b/docs/conf.py index 9fe997d..b52095c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -150,7 +150,7 @@ # html_logo = None # The name of an image file (relative to this directory) to use as a favicon of -# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. # # html_favicon = None @@ -158,7 +158,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['static'] +html_static_path = [] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -342,4 +342,4 @@ # # texinfo_no_detailmenu = False -autodoc_member_order = 'bysource' \ No newline at end of file +autodoc_member_order = 'bysource' diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..1aa4172 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,114 @@ +.. _contributing-page: + +Contributing +------------ + +Instructions +============ + +Before submitting a pull request on GitHub_, please make sure you meet the +**requirements**: + +* The pull request points to the dev_ (development) branch. +* All changes are squashed into a single commit (I like to use git rebase -i + to do this). +* The commit message is in present tense (good: "Add feature", bad: + "Added feature"). +* Correct and consistent style: Sphinx_-compatible docstrings, using snake + vs. camel casing properly_ and PEP8_ compliance. Use flake8_ (see below). +* No classes/methods/functions with missing docstrings or commented-out lines. + You can refer to existing docstrings for examples. +* The test coverage_ remains at %100. Sometimes you may find yourself having to + write superfluous unit tests to keep this number up. If a piece of code is + trivial and has no need for unittests, use this_ to exclude it from coverage. +* No build failures on TravisCI_. The builds automatically trigger on PR + submissions. +* Does not break backward-compatibility (unless there is a really good reason). +* Compatibility with all supported Python versions (2.7, 3.4, 3.5, 3.6). + +.. warning:: + The dev branch is occasionally rebased_, and its commit history may be + overwritten in the process (I try very hard never to do this). So before + you begin feature work, git fetch/pull to ensure that branches have not + diverged. If you see git conflicts and just want to start from scratch, + run this command: + + .. code-block:: bash + + ~$ git checkout dev + ~$ git fetch origin + ~$ git reset --hard origin/dev # THIS WILL WIPE ALL CHANGES + +Style +===== + +To ensure PEP8_ compliance, run flake8_: + +.. code-block:: bash + + ~$ pip install flake8 + ~$ git clone https://github.com/joowani/kq.git + ~$ cd kq + ~$ flake8 + +You should try to resolve all issues reported. If there is a good reason to +ignore errors from a specific piece of code, however, visit here_ to see how +to exclude the lines from the check. + +Testing +======= + +To test your changes, run the unit tests that come with **kq** on your +local machine. The tests use pytest_. + +To run the unit tests: + +.. code-block:: bash + + ~$ pip install pytest + ~$ git clone https://github.com/joowani/kq.git + ~$ cd kq + ~$ py.test --verbose + +To run the unit tests with coverage report: + +.. code-block:: bash + + ~$ pip install coverage pytest pytest-cov + ~$ git clone https://github.com/joowani/kq.git + ~$ cd kq + ~$ py.test --verbose --cov-report=html --cov=kq + ~$ # Open the generated file htmlcov/index.html in a browser + + +Documentation +============= + +The documentation (including the README) is written in reStructuredText_ and +uses Sphinx_. To build the HTML version of the documentation on your local +machine: + +.. code-block:: bash + + ~$ pip install sphinx sphinx_rtd_theme + ~$ git clone https://github.com/joowani/kq.git + ~$ cd kq/docs + ~$ sphinx-build . build + ~$ # Open the generated file build/index.html in a browser + + +As always, thanks for your contribution! + +.. _rebased: https://git-scm.com/book/en/v2/Git-Branching-Rebasing +.. _dev: https://github.com/joowani/kq/tree/dev +.. _GitHub: https://github.com/joowani/kq +.. _properly: https://stackoverflow.com/questions/159720 +.. _PEP8: https://www.python.org/dev/peps/pep-0008/ +.. _coverage: https://coveralls.io/github/joowani/kq +.. _this: http://coverage.readthedocs.io/en/latest/excluding.html +.. _TravisCI: https://travis-ci.org/joowani/kq +.. _Sphinx: https://github.com/sphinx-doc/sphinx +.. _flake8: http://flake8.pycqa.org +.. _here: http://flake8.pycqa.org/en/latest/user/violations.html#in-line-ignoring-errors +.. _pytest: https://github.com/pytest-dev/pytest +.. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText diff --git a/docs/index.rst b/docs/index.rst index 2942f91..1192b5c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,7 +13,7 @@ Requirements ============ - Apache Kafka 0.9+ -- Python 2.7+ 3.4+ or 3.5+ +- Python 2.7, 3.4, 3.5 or 3.6 Installation @@ -53,6 +53,7 @@ Contents callback cli logging + contributing Credits diff --git a/docs/overview.rst b/docs/overview.rst index edfbcee..b9ade57 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -55,4 +55,4 @@ Sit back and watch the worker process it in the background: [INFO] Job 1b92xle0 returned: (1, 2, 3) -And that's essentially all there is to KQ! Continue for more information. \ No newline at end of file +And that's essentially all there is to KQ! \ No newline at end of file diff --git a/kq/cli.py b/kq/cli.py index 0604102..25425d9 100644 --- a/kq/cli.py +++ b/kq/cli.py @@ -27,7 +27,7 @@ --certfile= Full path to SSL client certificate --keyfile= Full path to SSL private key --crlfile= Full path to SSL crlfile for verifying expiry - --proc-ttl= Records read before re-spawning process [default: 5000] + --proc-ttl= Records read before respawning process [default: 5000] --offset= Kafka consumer offset reset policy [default: latest] --verbose Turn on debug logging output --help Display this help menu diff --git a/kq/version.py b/kq/version.py index d0e714d..88f9db1 100644 --- a/kq/version.py +++ b/kq/version.py @@ -1 +1 @@ -VERSION = '1.3.1' +VERSION = '1.3.2' diff --git a/kq/worker.py b/kq/worker.py index fac88e2..3dd5334 100644 --- a/kq/worker.py +++ b/kq/worker.py @@ -184,9 +184,10 @@ def _consume_record(self, record): """ rec = rec_repr(record) self._logger.info('Processing {} ...'.format(rec)) + # noinspection PyBroadException try: job = dill.loads(record.value) - except: + except Exception: self._logger.warning('{} unloadable. Skipping ...'.format(rec)) else: # Simple check for job validity diff --git a/tests/test_queue.py b/tests/test_queue.py index 92af221..9789680 100644 --- a/tests/test_queue.py +++ b/tests/test_queue.py @@ -161,7 +161,7 @@ def test_enqueue_job(producer, logger): assert new_job.args == [1, 2] assert new_job.kwargs == {'a': 3} assert new_job.timeout == 300 - assert new_job.key == None + assert new_job.key is None producer_inst.send.assert_called_with( 'foo', dill.dumps(new_job), key=None @@ -223,4 +223,3 @@ def test_flush(producer): queue = Queue(hosts='host:7000', topic='foo') queue.flush() producer_inst.flush.assert_called_once() - diff --git a/tests/test_worker.py b/tests/test_worker.py index 71c3768..3c8a1d0 100644 --- a/tests/test_worker.py +++ b/tests/test_worker.py @@ -279,4 +279,4 @@ def test_start_proc_ttl_reached(logger, callback): ]) callback.assert_called_with( 'success', success_job, (1, 2, 3), None, None - ) \ No newline at end of file + )