Fix project's metadata. Add common READMEs (allure-framework#799)

allure-behave/setup.py

@@ -51,7 +51,7 @@ def main():
             "Documentation": "https://allurereport.org/docs/behave/",
             "Source": "https://github.com/allure-framework/allure-python",
         },
-        author="QAMetaSoftware, Stanislav Seliverstov",
+        author="Qameta Software Inc., Stanislav Seliverstov",
         author_email="[email protected]",
         license="Apache-2.0",
         classifiers=classifiers,

allure-nose2/setup.py

@@ -49,7 +49,7 @@ def main():
         project_urls={
             "Source": "https://github.com/allure-framework/allure-python",
         },
-        author="QAMetaSoftware, Stanislav Seliverstov",
+        author="Qameta Software Inc., Stanislav Seliverstov",
         author_email="[email protected]",
         license="Apache-2.0",
         classifiers=classifiers,

allure-pytest-bdd/setup.py

@@ -51,7 +51,7 @@ def main():
         project_urls={
             "Source": "https://github.com/allure-framework/allure-python",
         },
-        author="QAMetaSoftware, Stanislav Seliverstov",
+        author="Qameta Software Inc., Stanislav Seliverstov",
         author_email="[email protected]",
         license="Apache-2.0",
         classifiers=classifiers,

allure-pytest/setup.py

@@ -64,7 +64,7 @@ def main():
             "Documentation": "https://allurereport.org/docs/pytest/",
             "Source": "https://github.com/allure-framework/allure-python",
         },
-        author="QAMetaSoftware, Stanislav Seliverstov",
+        author="Qameta Software Inc., Stanislav Seliverstov",
         author_email="[email protected]",
         license="Apache-2.0",
         classifiers=classifiers,

allure-python-commons-test/README.md

@@ -0,0 +1,62 @@
+## Allure Python Testing Utilities
+
+[![Release Status](https://img.shields.io/pypi/v/allure-python-commons-test)](https://pypi.python.org/pypi/allure-python-commons-test)
+[![Downloads](https://img.shields.io/pypi/dm/allure-python-commons-test)](https://pypi.python.org/pypi/allure-python-commons-test)
+
+> The package contains pyhamcrest matchers to assert the Allure results. They
+> come in handy when you need to test an Allure adapter.
+
+[<img src="https://allurereport.org/public/img/allure-report.svg" height="85px" alt="Allure Report logo" align="right" />](https://allurereport.org "Allure Report")
+
+- Learn more about Allure Report at [https://allurereport.org](https://allurereport.org)
+- 📚 [Documentation](https://allurereport.org/docs/) – discover official documentation for Allure Report
+- ❓ [Questions and Support](https://github.com/orgs/allure-framework/discussions/categories/questions-support) – get help from the team and community
+- 📢 [Official announcements](https://github.com/orgs/allure-framework/discussions/categories/announcements) –  stay updated with our latest news and updates
+- 💬 [General Discussion](https://github.com/orgs/allure-framework/discussions/categories/general-discussion) – engage in casual conversations, share insights and ideas with the community
+- 🖥️ [Live Demo](https://demo.allurereport.org/) — explore a live example of Allure Report in action
+
+---
+
+## The matchers library
+
+Here is the list of available matchers. Refer to [https://github.com/allure-framework/allure-python/tree/master/tests](https://github.com/allure-framework/allure-python/tree/master/tests) for usage examples.
+
+|Module|Matcher|Check|
+|------|-------|-----|
+|container|`has_container`|The report contains a container that matches all the provided matchers.|
+|container|`has_same_container`|The report contains a container that has all the specified tests as its children|
+|container|`has_before`|The container has a before fixture with the specified name that matches all the provided matchers|
+|container|`has_after`|The container has an after fixture with the specified name that matches all the provided matchers|
+|content|`csv_equivalent`|The string (typically, an attachment's content) contains a CSV document that is equvalent to the provided one|
+|label|`has_label`|The test contains a label with the specified name and (optionaly) the value|
+|label|`has_severity`|The test has the specified severity label|
+|label|`has_epic`|The test has the specified epic label|
+|label|`has_feature`|The test has the specified feature label|
+|label|`has_story`|The test has the specified story label|
+|label|`has_tag`|The test has the specified tag label|
+|label|`has_package`|The test has the specified package label|
+|label|`has_suite`|The test has the specified suite label|
+|label|`has_parent_suite`|The test has the specified parentSuite label|
+|label|`has_sub_suite`|The test has the specified subSuite label|
+|report|`has_test_case`|The report contains a test whose fullName ends, or name starts with the specified name. Additionally, the test must match all the provided matchers|
+|report|`has_only_testcases`|Each test of the report matches at least one of the provided matchers|
+|report|`has_only_n_test_cases`|Same as `has_test_case` but also checks if the number of matched tests is equal to the expected one|
+|result|`has_title`|The test has an expected name|
+|result|`has_description`|The test has a description that matches all the provided matchers|
+|result|`has_description_html`|The test has a descriptionHtml that matches all the provided matchers|
+|result|`has_step`|The test or step has a step with the specified name that matches all the provided matchers|
+|result|`has_parameter`|The test or step has a parameter with the specified name whose value matches the provided matchers|
+|result|`doesnt_have_parameter`|The test or step doesn't have a parameter with the specified name|
+|result|`has_link`|The test has a link with the expected url, type (if provided) and name (if provided)|
+|result|`has_issue_link`|The test has an issue link with the expected url and name (if provided)|
+|result|`has_test_case_link`|The test has an issue link with the expected url and name (if provided)|
+|result|`has_attachment`|The test or step has an attachment with the expected name and type.|
+|result|`has_attachment_with_content`|The test or step has an attachment with the expected name and type. In addition, the content must match the provided matcher.|
+|result|`with_id`|The test or container has the expected uuid|
+|result|`with_status`|The test or step has the expected status|
+|result|`has_status_details`|The status details of the test or step matches all the provided matchers|
+|result|`with_message_contains`|The status details' message contains the provided text|
+|result|`with_trace_contains`|The status details' trace contains the provided text|
+|result|`with_excluded`|The parameter is excluded from the historyId calculation|
+|result|`with_mode`|The parameter has the specified mode|
+|result|`has_history_id`|The test has historyId|

allure-python-commons-test/setup.py

@@ -1,22 +1,53 @@
+import os
 from setuptools import setup
 
 PACKAGE = "allure-python-commons-test"
 
+classifiers = [
+    'Development Status :: 5 - Production/Stable',
+    'Intended Audience :: Developers',
+    'License :: OSI Approved :: Apache Software License',
+    'Topic :: Software Development :: Quality Assurance',
+    'Topic :: Software Development :: Testing',
+    'Programming Language :: Python :: 3',
+    'Programming Language :: Python :: 3 :: Only',
+    'Programming Language :: Python :: 3.7',
+    'Programming Language :: Python :: 3.8',
+    'Programming Language :: Python :: 3.9',
+    'Programming Language :: Python :: 3.10',
+    'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
+]
+
 install_requires = [
     "pyhamcrest>=1.9.0"
 ]
 
 
+def get_readme(fname):
+    return open(os.path.join(os.path.dirname(__file__), fname)).read()
+
+
 def main():
     setup(
         name=PACKAGE,
         use_scm_version={"root": "..", "relative_to": __file__},
         setup_requires=['setuptools_scm'],
-        description="Common module for self-testing allure integrations with python-based frameworks",
-        url="https://github.com/allure-framework/allure-python",
-        author="QAMetaSoftware, Stanislav Seliverstov",
+        description=(
+            "A collection of PyHamcrest matchers to test Allure adapters for "
+            "Python test frameworks"
+        ),
+        url="https://allurereport.org/",
+        project_urls={
+            "Source": "https://github.com/allure-framework/allure-python",
+        },
+        author="Qameta Software Inc., Stanislav Seliverstov",
         author_email="[email protected]",
         license="Apache-2.0",
+        classifiers=classifiers,
+        keywords="allure reporting testing matchers",
+        long_description=get_readme("README.md"),
+        long_description_content_type="text/markdown",
         packages=["allure_commons_test"],
         package_dir={"allure_commons_test": "src"},
         install_requires=install_requires

allure-python-commons/README.md

@@ -0,0 +1,112 @@
+## Allure Common API
+
+[![Release Status](https://img.shields.io/pypi/v/allure-python-commons)](https://pypi.python.org/pypi/allure-python-commons)
+[![Downloads](https://img.shields.io/pypi/dm/allure-python-commons)](https://pypi.python.org/pypi/allure-python-commons)
+
+> The package contains classes and functions for users of Allure Report. It can
+> be used to enhance reports using an existing Allure adapter or to create new
+> adapters.
+
+[<img src="https://allurereport.org/public/img/allure-report.svg" height="85px" alt="Allure Report logo" align="right" />](https://allurereport.org "Allure Report")
+
+- Learn more about Allure Report at [https://allurereport.org](https://allurereport.org)
+- 📚 [Documentation](https://allurereport.org/docs/) – discover official documentation for Allure Report
+- ❓ [Questions and Support](https://github.com/orgs/allure-framework/discussions/categories/questions-support) – get help from the team and community
+- 📢 [Official announcements](https://github.com/orgs/allure-framework/discussions/categories/announcements) –  stay updated with our latest news and updates
+- 💬 [General Discussion](https://github.com/orgs/allure-framework/discussions/categories/general-discussion) – engage in casual conversations, share insights and ideas with the community
+- 🖥️ [Live Demo](https://demo.allurereport.org/) — explore a live example of Allure Report in action
+
+---
+
+## User's API
+
+Install an adapter that suits your test framework. You can then add more
+information to the report by using functions from the `allure` module.
+
+### Decorators API
+
+Use these functions as decorators of your own functions, e.g.:
+
+```python
+import allure
+
+@allure.title("My test")
+def test_fn():
+    pass
+```
+
+The full list of decorators:
+
+  - `allure.title`
+  - `allure.description`
+  - `allure.description_html`
+  - `allure.label`
+  - `allure.severity`
+  - `allure.epic`
+  - `allure.feature`
+  - `allure.story`
+  - `allure.suite`
+  - `allure.parent_suite`
+  - `allure.sub_suite`
+  - `allure.tag`
+  - `allure.id`
+  - `allure.manual`
+  - `allure.link`
+  - `allure.issue`
+  - `allure.testcase`
+  - `allure.step`
+
+Refer to the adapter's documentation for the information about what decorators
+are supported and what functions they can be applied to.
+
+### Runtime API
+
+Most of the functions of Runtime API can be accessed via `allure.dynamic.*`.
+Call them at runtime from your code.
+
+The full list includes:
+
+  - `allure.dynamic.title`
+  - `allure.dynamic.description`
+  - `allure.dynamic.description_html`
+  - `allure.dynamic.label`
+  - `allure.dynamic.severity`
+  - `allure.dynamic.epic`
+  - `allure.dynamic.feature`
+  - `allure.dynamic.story`
+  - `allure.dynamic.suite`
+  - `allure.dynamic.parent_suite`
+  - `allure.dynamic.sub_suite`
+  - `allure.dynamic.tag`
+  - `allure.dynamic.id`
+  - `allure.dynamic.manual`
+  - `allure.dynamic.link`
+  - `allure.dynamic.issue`
+  - `allure.dynamic.testcase`
+  - `allure.dynamic.parameter`
+  - `allure.attach`
+  - `allure.attach.file`
+  - `allure.step`
+
+Refer to the adapter's documentation for the information about what functions
+are supported and where you can use them.
+
+## Adapter API
+
+You may use `allure-pytest-commons` to build your own Allure adapter. The key
+elements of the corresponding API are:
+
+  - `allure_python_commons.model2`: the object model of Allure Report.
+  - `allure_python_commons.logger`: classes that are used to emit Allure Report objects (tests, containers, attachments):
+      - `AllureFileLogger`: emits to the file system.
+      - `AllureMemoryLogger`: collects the objects in memory. Useful for
+        testing.
+  - `allure_python_commons.lifecycle.AllureLifecycle`: an implementation of
+    Allure lifecycle that doesn't isolate the state between threads.
+  - `allure_python_commons.reporter.AllureReporter`: an implementation of
+    Allure lifecycle that supports some multithreaded scenarios.
+
+A new version of the API is likely to be released in the future as we need
+a decent support for multithreaded and async-based concurrency (see
+[here](https://github.com/allure-framework/allure-python/issues/697) and
+[here](https://github.com/allure-framework/allure-python/issues/720)).

allure-python-commons/setup.py

@@ -1,3 +1,4 @@
+import os
 from setuptools import setup
 
 PACKAGE = "allure-python-commons"
@@ -24,21 +25,30 @@
 ]
 
 
+def get_readme(fname):
+    return open(os.path.join(os.path.dirname(__file__), fname)).read()
+
+
 def main():
     setup(
         name=PACKAGE,
         use_scm_version={"root": "..", "relative_to": __file__},
         setup_requires=['setuptools_scm'],
-        description="Common module for integrate allure with python-based frameworks",
+        description=(
+            "Contains the API for end users as well as helper functions and "
+            "classes to build Allure adapters for Python test frameworks",
+        ),
         url="https://allurereport.org/",
         project_urls={
             "Source": "https://github.com/allure-framework/allure-python",
         },
-        author="QAMetaSoftware, Stanislav Seliverstov",
+        author="Qameta Software Inc., Stanislav Seliverstov",
         author_email="[email protected]",
         license="Apache-2.0",
         classifiers=classifiers,
         keywords="allure reporting report-engine",
+        long_description=get_readme("README.md"),
+        long_description_content_type="text/markdown",
         packages=["allure_commons"],
         package_dir={"allure_commons": 'src'},
         install_requires=install_requires,