diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0a16087 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +**/*.pyc +.venv +.*cache +build +dist \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..098f12a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,86 @@ +Contributing +============ + +Contributions are welcome, and they are greatly appreciated! Every little bit +helps, and credit will always be given. + +You can contribute in many ways: + +Types of Contributions +---------------------- + +### Report Bugs + +Report bugs at pydicom/pylibjpeg-turbo/issues. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting. +* Detailed steps to reproduce the bug. + +### Fix Bugs + +Look through the GitHub issues for bugs. Anything tagged with "bug" and "help +wanted" is open to whoever wants to implement it. + +### Implement Features + +Look through the GitHub issues for features. Anything tagged with "enhancement" +and "help wanted" is open to whoever wants to implement it. + +### Write Documentation + +pylibjpeg-turbo could always use more documentation, whether as part of the +official pylibjpeg-turbo docs, in docstrings, or even on the web in blog posts, +articles, and such. + +### Submit Feedback + +The best way to send feedback is to file an issue at pydicom/pylibjpeg-turbo/issues. + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that contributions + are welcome :) + +Get Started! +------------ + +Ready to contribute? Here's how to set up `pylibjpeg_turbo` for local development. + +1. Fork the `pylibjpeg_turbo` repo on GitHub. +2. Clone your fork locally:: + + `$ git clone git@github.com:your_name_here/pylibjpeg_turbo.git` + + +3. Create a branch for local development:: + + `$ git checkout -b name-of-your-bugfix-or-feature` + + Now you can make your changes locally. + + +4. Commit your changes and push your branch to GitHub:: + + ``` + $ git add . + $ git commit -m "Your detailed description of your changes." + $ git push origin name-of-your-bugfix-or-feature + ``` + +5. Submit a pull request through the GitHub website. + + +Pull Request Guidelines +----------------------- + +Before you submit a pull request, check that it meets these guidelines: + +1. The pull request should include tests. +2. If the pull request adds functionality, the docs should be updated. Put + your new functionality into a function with a docstring, and add the + feature to the list in README.md and CHANGES.md diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..620ddc8 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,138 @@ +Copyright (c) 2023, Darcy Mason and pylibjpeg-turbo authors +All rights reserved. + +By linking to the libjpeg-turbo library, this software is based in part on the work of the Independent JPEG Group, and is released under BSD-style licenses as per the wrapped libjpeg-turbo library: + + +libjpeg-turbo Licenses +====================== + +libjpeg-turbo is covered by three compatible BSD-style open source licenses: + +- The IJG (Independent JPEG Group) License, which is listed in + [README.ijg](README.ijg) + + This license applies to the libjpeg API library and associated programs + (any code inherited from libjpeg, and any modifications to that code.) + +- The Modified (3-clause) BSD License, which is listed below + + This license covers the TurboJPEG API library and associated programs, as + well as the build system. + +- The [zlib License](https://opensource.org/licenses/Zlib) + + This license is a subset of the other two, and it covers the libjpeg-turbo + SIMD extensions. + + +Complying with the libjpeg-turbo Licenses +========================================= + +This section provides a roll-up of the libjpeg-turbo licensing terms, to the +best of our understanding. + +1. If you are distributing a modified version of the libjpeg-turbo source, + then: + + 1. You cannot alter or remove any existing copyright or license notices + from the source. + + **Origin** + - Clause 1 of the IJG License + - Clause 1 of the Modified BSD License + - Clauses 1 and 3 of the zlib License + + 2. You must add your own copyright notice to the header of each source + file you modified, so others can tell that you modified that file (if + there is not an existing copyright header in that file, then you can + simply add a notice stating that you modified the file.) + + **Origin** + - Clause 1 of the IJG License + - Clause 2 of the zlib License + + 3. You must include the IJG README file, and you must not alter any of the + copyright or license text in that file. + + **Origin** + - Clause 1 of the IJG License + +2. If you are distributing only libjpeg-turbo binaries without the source, or + if you are distributing an application that statically links with + libjpeg-turbo, then: + + 1. Your product documentation must include a message stating: + + This software is based in part on the work of the Independent JPEG + Group. + + **Origin** + - Clause 2 of the IJG license + + 2. If your binary distribution includes or uses the TurboJPEG API, then + your product documentation must include the text of the Modified BSD + License (see below.) + + **Origin** + - Clause 2 of the Modified BSD License + +3. You cannot use the name of the IJG or The libjpeg-turbo Project or the + contributors thereof in advertising, publicity, etc. + + **Origin** + - IJG License + - Clause 3 of the Modified BSD License + +4. The IJG and The libjpeg-turbo Project do not warrant libjpeg-turbo to be + free of defects, nor do we accept any liability for undesirable + consequences resulting from your use of the software. + + **Origin** + - IJG License + - Modified BSD License + - zlib License + + +The Modified (3-clause) BSD License +=================================== + +Copyright (C)2009-2023 D. R. Commander. All Rights Reserved.
+Copyright (C)2015 Viktor Szathmáry. All Rights Reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +- Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. +- Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. +- Neither the name of the libjpeg-turbo Project nor the names of its + contributors may be used to endorse or promote products derived from this + software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS", +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. + + +Why Three Licenses? +=================== + +The zlib License could have been used instead of the Modified (3-clause) BSD +License, and since the IJG License effectively subsumes the distribution +conditions of the zlib License, this would have effectively placed +libjpeg-turbo binary distributions under the IJG License. However, the IJG +License specifically refers to the Independent JPEG Group and does not extend +attribution and endorsement protections to other entities. Thus, it was +desirable to choose a license that granted us the same protections for new code +that were granted to the IJG for code derived from their software. diff --git a/README.md b/README.md index e69de29..9357637 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,22 @@ +pylibjpeg-turbo +=============== +(** This README is a Work in Progress) + + +A builder of Python wheels to access the libjpeg-turbo library, mainly intended for use as a plugin for [pydicom](https://github.com/pydicom/pydicom). + +The library has no Python bindings, but is meant to be used through Python's [ctypes](https://docs.python.org/3/library/ctypes.html). The [PyTurboJPEG](https://github.com/lilohuang/PyTurboJPEG) library is included as a dependency, and its `ctypes` access is used by the pydicom plugin. + + + + + + +## Development + +To install the development version of pylibjpeg-turbo: + + git clone --recursive https://github.com/pydicom/pylibjpeg-turbo + cd pylibjpeg_turbo + python -m pip install -e .[dev] + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..e12b1f0 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,17 @@ +site_name: pylibjpeg-turbo Docs + +nav: + - Introduction: index.md + - Tutorials: tutorials.md + - How-To Guides: how-to-guides.md + - Reference: reference.md + - Explanation: explanation.md + +repo_url: https://github.com/pydicom/pylibjpeg-turbo + +theme: + name: readthedocs + highlightjs: true + +plugins: + - mkdocstrings diff --git a/pyproject.toml b/pyproject.toml index 1d3da7a..1724562 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,20 +1,18 @@ -# pyproject.toml -# py-build-cmake help from https://github.com/tttapa/py-build-cmake/issues/16 [build-system] requires = ["py-build-cmake~=0.1.9a3"] build-backend = "py_build_cmake.build" - -# --------------- Project ------------------- +# -------- Project --------------------------------------- [project] name = "pylibjpeg-turbo" readme = "README.md" -requires-python = ">=3.9" -license = { "file" = "LICENSE" } +requires-python = ">=3.7" +license = { file = "LICENSE" } authors = [{ name = "Darcy Mason", email = "darcymason@gmail.com" }] version = "0.1.0" -description = "libjpeg-turbo wrapper, primarily for pydicom plugin" +description = "Python build of libjpeg-turbo for pydicom plugin" + # see https://pypi.org/classifiers/ classifiers = [ "Development Status :: 2 - Pre-Alpha", @@ -26,9 +24,7 @@ classifiers = [ "License :: OSI Approved :: BSD License", ] -dependencies = [ - "PyTurboJPEG" -] +dependencies = ["PyTurboJPEG"] [project.urls] Source = "https://github.com/pydicom/pylibjpeg-turbo" @@ -68,8 +64,9 @@ pylibjpeg_turbo = "pylibjpeg_turbo:decode" [project.entry-points."pylibjpeg.jpeg_xt_decoders"] pylibjpeg_turbo = "pylibjpeg_turbo:decode" - -# --------------- cmake / build ------------------- +# ------ cmake / build ---------------------------------- +# See https://github.com/tttapa/py-build-cmake-libjpeg-turbo +# (resulting from https://github.com/tttapa/py-build-cmake/issues/16) [tool.py-build-cmake.sdist] include = ["CMakeLists.txt", "extern/libjpeg-turbo"] @@ -83,3 +80,60 @@ abi = 'none' [tool.cibuildwheel] build-verbosity = 1 environment = { PY_BUILD_CMAKE_VERBOSE="1" } + +# --------- linters / formatting ------------------------- +[tool.black] +include = '\.pyi?$' +extend-exclude = ''' +# A regex preceded with ^/ will apply only to files and directories +# in the root of the project. +^/.git +^/.tox +^/.venv +^/.build +^/.dist +''' + +[tool.ruff] +# see https://github.com/charliermarsh/ruff +select = ["ALL"] +ignore = [ + # ignored for now, should be activated in the future + # docstrings + "D", + # flake8-annotations + "ANN", + # flake8-type-checking + "TCH", + + # ignored, "black" will handle this + # flake8-commas + "COM", + + # ignored, due to Windows / WSL2 setup + # flake8-executable + "EXE", +] +fixable = ["I"] +fix = true +target-version = "py38" + +[tool.ruff.per-file-ignores] +# see https://github.com/charliermarsh/ruff +"tests/*" = ["FBT003", "INP001", "PLR2004", "S101", "SLF001"] + +[tool.ruff.pydocstyle] +convention = "pep257" # Accepts: "google", "numpy", or "pep257". + + +# --------- Testing -------------------------------------- +[tool.pytest.ini_options] +markers = [ + "functional: marks tests as functional (deselect with '-m \"not functional\"')", +] +addopts = [ + "--strict-markers", + "--strict-config", + "--showlocals", + "-ra", +] diff --git a/tests/_pydicom-logo.jpg b/tests/_pydicom-logo.jpg new file mode 100644 index 0000000..4bcc30c Binary files /dev/null and b/tests/_pydicom-logo.jpg differ diff --git a/tests/test_jpeg_file.py b/tests/test_jpeg_file.py new file mode 100644 index 0000000..f1654c7 --- /dev/null +++ b/tests/test_jpeg_file.py @@ -0,0 +1,12 @@ + +import pytest +from pathlib import Path + +from pylibjpeg_turbo import decode + + +HERE = Path(__file__).parent + +def test_jpeg_file(): + """Decode a simple jpg file""" + decode(HERE / "_pydicom-logo.jpg")