Merge pull request #9 from nexB/new-skeleton

Improve code, doc and adopt latest skeleton

Author: pombredanne

.gitattributes

@@ -1,2 +1,3 @@
 # Ignore all Git auto CR/LF line endings conversions
 * -text
+pyproject.toml export-subst

.gitignore

@@ -7,12 +7,12 @@
 /build
 /bin
 /lib
-/venv
 /scripts
 /Scripts
 /Lib
 /pip-selfcheck.json
 /tmp
+/venv
 .Python
 /include
 /Include

.travis.yml

@@ -13,9 +13,10 @@ python:
   - "3.6"
   - "3.7"
   - "3.8"
+  - "3.9"
 
 # Scripts to run at install stage
-install: pip install ./ && pip install -r requirements-dev.txt
+install: ./configure --dev
 
 # Scripts to run at script stage
-script: python -m  pytest
+script: venv/bin/pytest

AUTHORS.rst

@@ -1,3 +1,6 @@
 The following organizations or individuals have contributed to this repo:
 
-- 
+- Shivam Sandbhor
+- nexB Inc.
+- Philippe Ombredanne
+

CHANGELOG.rst

@@ -1,15 +1,26 @@
 Release notes
 -------------
+
+### Version v30.0.0
+
+- Switching back to semver
+- Improve origin and license documentation
+- Add tests for carets in RPMs
+- Format, stremmline and refactor code
+- Improve testing
+
+
 ### Version v21.4.9
 
-- Added support Gentoo style versions. 
+- Add support Gentoo style versions. 
+
 
 ### Version v21.4.8
 
-- More package types supported.
-- Version classes are hashable and frozen now
+- Add support for more package types.
+- Version classes are now hashable and frozen
+
 
 ### Version v21.4.6
 
 - Initial Release
-

NOTICE

@@ -2,7 +2,8 @@
 # Copyright (c) nexB Inc. and others.
 # SPDX-License-Identifier: Apache-2.0
 #
-# Visit https://aboutcode.org and https://github.com/nexB/ for support and download.
+# Visit https://aboutcode.org and https://github.com/nexB/vulnerablecode
+# for support and download.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,3 +16,4 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+#

README.rst

@@ -1,5 +1,5 @@
-Univers: Ecosystem specific version comparision and conversion
-==============================================================
+univers: mostly universal version and version ranges comparison and conversion
+===============================================================================
 
 |Build Status| |License| |Python 3.6+|
 
@@ -11,43 +11,76 @@ Univers: Ecosystem specific version comparision and conversion
 
 
 
-Why ecosystem specific ?
-========================
+univers was born out of the need for a mostly univeral way to perform software
+package version comparisons in VulnerableCode.
 
-Univers was born out of the need for version comparision at VulnerableCode. Existing
-tools follow a particular algorithm to evaluate and compare versions. This is not 
-accurate across different ecosystems, since they follow different versioning rules. For 
-example there's no concept of 'epoch' in  semver based ecosystem like npm or ruby gems, but
-epochs do exist in  debian ecosystem. The tools solely based on semver or dpkg version spec therefore
-give different and wrong results in both cases.
+Package version ranges and version constraints are useful and essential:
 
-Univers is different, it considers the ecosystem of version.
+- When resolving the dependencies of a package to express which subset of the
+  versions are supported. For instance a dependency requirement statement such
+  as "I require package foo, version 2.0 and later versions" defines a range of
+  acceptable foo versions.
 
-How Univers works ?
-===================
+- When relating a known vulnerability or bug to a range of affected package
+  versions. For instance a statement such as "vulnerability 123 affects 
+  package bar, version 3.1 and version 4.2 but not version 5" also defines a
+  range of affected bar versions.
 
-Univers, can be considered as a wrapper around many version comparision libraries, each of which
-solving the problem for the respective ecosystem. It delegates the actual comparision to these libraries
-depending upon the ecosystem.
+Existing tools support typically a single algorithm to parse and compare
+versions and this is not accurate across different ecosystems, since each
+follow different versioning rules. For example there's no concept of 'epoch' in
+semver versioning as used in package types and ecosystem such as npm or
+rubygems, but epochs do exist in debian versions. A tool designed for semver or
+dpkg versions processing would not be able to handle correctly the other version
+scheme.
 
+univers is different and considers the ecosystem-specific version scheme used.
 
-The supported ecosystems and underlying libraries are: 
 
-- npm, golang, php-composer, ruby-gems and others which follow the semver spec. These use `semantic_version <https://github.com/rbarrois/python-semanticversion>`_ library.
-- debian, this is handled by `debian-inspector <https://github.com/sbs2001/univers/blob/main/src/univers/debian.py.ABOUT>`_ library.
-- pypi, this is handled by Python's ``packaging.version`` module.
-- maven, this is handled by   `rpm_vercmp <https://github.com/sbs2001/univers/blob/main/src/univers/rpm.py.ABOUT>`_ library.
-- ebuild/gentoo, this is handled by `gentoo_vercmp <https://github.com/sbs2001/univers/blob/main/src/univers/gentoo.py.ABOUT>`_ module.
+How does univers work ?
+=========================
+
+univers wraps, embeds or implements multiple version comparision libraries, each
+focused on specific ecosystem version scheme.
+
+It also implements an experimental unified syntax for version ranges specifier
+and can parse and convert existing version range strings to this unified syntax.
+
+
+The supported package ecosystems versioning schemes and underlying libraries are:
+
+- semver: npm, golang, PHP composer, rubygems and others that follow the semver
+  spec, using `semantic_version <https://github.com/rbarrois/python-semanticversion>`_ library.
+- debian: handled by the 
+  `debian-inspector <https://github.com/sbs2001/univers/blob/main/src/univers/debian.py.ABOUT>`_
+  library.
+- pypi: handled by Python's packaging library and the standard ``packaging.version`` module.
+- maven: handled by the embedded `rpm_vercmp <https://github.com/sbs2001/univers/blob/main/src/univers/rpm.py.ABOUT>`_ library.
+- ebuild/gentoo: handled by the embedded `gentoo_vercmp <https://github.com/sbs2001/univers/blob/main/src/univers/gentoo.py.ABOUT>`_ module.
+
+As we grow, new schemes will be implemented accordingly.
+
+
+Alternative
+============
+
+Rather than using ecosystem-specific version schemes and code, another approach
+is to use a single procedure for all the versions as implemented in `libversion
+<https://github.com/repology/libversion>`_. This works in the most common case
+but may not work correctly for specific tasks that demand accurate version
+comparison such as for dependency resolution and vulnerabilities checks.
+
 
 Installation
 ============
 
-        $ pip install univers
+    $ pip install univers
+
 
 Examples
 ========
 
-Comparing discrete versions
+Compare two versions using the Python comparison operators:
 
 .. code:: python
 
@@ -57,7 +90,7 @@ Comparing discrete versions
     assert v1 < v2 == True
 
 
-Evaluating version ranges
+Test if a version is within or outside of a version range:
 
 .. code:: python
 
@@ -70,3 +103,23 @@ Evaluating version ranges
 
     assert (v1 in vs ) == True
     assert (v2 in vs ) == False
+
+
+Development
+============
+
+Starting from a git clone of https://github.com/nexB/univers run these::
+
+    $ configure --dev
+    $ source venv/bin/active
+    $ pytest -vvs
+
+
+We use the same development process as other AboutCode projects.
+
+Visit https://github.com/nexB/univers and
+https://gitter.im/aboutcode-org/vulnerablecode and
+https://gitter.im/aboutcode-org/aboutcode for support and chat.
+
+Primary license: Apache-2.0
+SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause AND MIT

azure-pipelines.yml

@@ -7,58 +7,50 @@
 
 jobs:
 
-    - template: etc/ci/azure-linux.yml
-      parameters:
-          job_name: ubuntu16_cpython
-          image_name: ubuntu-16.04
-          python_versions: ['3.6', '3.7', '3.8', '3.9']
-          test_suites:
-              all: tmp/bin/pytest -vvs
-
-    - template: etc/ci/azure-linux.yml
+    - template: etc/ci/azure-posix.yml
       parameters:
           job_name: ubuntu18_cpython
           image_name: ubuntu-18.04
-          python_versions: ['3.6', '3.7', '3.8', '3.9']
+          python_versions: ['3.6', '3.7', '3.8', '3.9', '3.10']
           test_suites:
-              all: tmp/bin/pytest -n 2 -vvs
+              all: venv/bin/pytest -n 2 -vvs
 
-    - template: etc/ci/azure-linux.yml
+    - template: etc/ci/azure-posix.yml
       parameters:
           job_name: ubuntu20_cpython
           image_name: ubuntu-20.04
-          python_versions: ['3.6', '3.7', '3.8', '3.9']
+          python_versions: ['3.6', '3.7', '3.8', '3.9', '3.10']
           test_suites:
-              all: tmp/bin/pytest -n 2 -vvs
+              all: venv/bin/pytest -n 2 -vvs
 
-    - template: etc/ci/azure-mac.yml
+    - template: etc/ci/azure-posix.yml
       parameters:
           job_name: macos1014_cpython
           image_name: macos-10.14
           python_versions: ['3.6', '3.7', '3.8', '3.9']
           test_suites:
-              all: tmp/bin/pytest -n 2 -vvs
+              all: venv/bin/pytest -n 2 -vvs
 
-    - template: etc/ci/azure-mac.yml
+    - template: etc/ci/azure-posix.yml
       parameters:
           job_name: macos1015_cpython
           image_name: macos-10.15
-          python_versions: ['3.6', '3.7', '3.8', '3.9']
+          python_versions: ['3.6', '3.7', '3.8', '3.9', '3.10']
           test_suites:
-              all: tmp/bin/pytest -n 2 -vvs
+              all: venv/bin/pytest -n 2 -vvs
 
     - template: etc/ci/azure-win.yml
       parameters:
           job_name: win2016_cpython
           image_name: vs2017-win2016
-          python_versions: ['3.6', '3.7', '3.8', '3.9']
+          python_versions: ['3.6', '3.7', '3.8', '3.9', '3.10']
           test_suites:
-              all: tmp\Scripts\pytest -n 2 -vvs
+              all: venv\Scripts\pytest -n 2 -vvs
 
     - template: etc/ci/azure-win.yml
       parameters:
           job_name: win2019_cpython
           image_name: windows-2019
-          python_versions: ['3.6', '3.7', '3.8', '3.9']
+          python_versions: ['3.6', '3.7', '3.8', '3.9', '3.10']
           test_suites:
-              all: tmp\Scripts\pytest -n 2 -vvs
+              all: venv\Scripts\pytest -n 2 -vvs

bsd-new.LICENSE

@@ -0,0 +1,24 @@
+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 ORGANIZATION 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 HOLDER 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.