Repository: incubator-ariatosca Updated Branches: refs/heads/packaging 43fa672fc -> a06335f83 (forced update)
packaging changelog and contributing files added badges added long description removed todo.md Project: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/commit/a06335f8 Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/a06335f8 Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/a06335f8 Branch: refs/heads/packaging Commit: a06335f834319d1ba09e5b6d50b5a28895c309d7 Parents: b6d3c43 Author: Ran Ziv <[email protected]> Authored: Mon Jun 5 13:24:49 2017 +0300 Committer: Ran Ziv <[email protected]> Committed: Mon Jun 5 16:24:43 2017 +0300 ---------------------------------------------------------------------- CHANGELOG.rst | 4 + CONTRIBUTING | 3 + DISCLAIMER | 10 ++ MANIFEST.in | 1 + README.md | 201 -------------------------------- README.rst | 328 +++++++++++++++++++++++++++++++++++++++++++++++++++++ TODO.md | 8 -- setup.py | 8 +- 8 files changed, 353 insertions(+), 210 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/a06335f8/CHANGELOG.rst ---------------------------------------------------------------------- diff --git a/CHANGELOG.rst b/CHANGELOG.rst new file mode 100644 index 0000000..6abb1af --- /dev/null +++ b/CHANGELOG.rst @@ -0,0 +1,4 @@ +0.1.0 +----- + + * Initial release. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/a06335f8/CONTRIBUTING ---------------------------------------------------------------------- diff --git a/CONTRIBUTING b/CONTRIBUTING new file mode 100644 index 0000000..4124003 --- /dev/null +++ b/CONTRIBUTING @@ -0,0 +1,3 @@ +Contribution guide is available on our Confluence: + +https://cwiki.apache.org/confluence/display/ARIATOSCA/Contributing+to+ARIA \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/a06335f8/DISCLAIMER ---------------------------------------------------------------------- diff --git a/DISCLAIMER b/DISCLAIMER new file mode 100644 index 0000000..358d8e1 --- /dev/null +++ b/DISCLAIMER @@ -0,0 +1,10 @@ +Apache AriaTosca is an effort undergoing incubation at the Apache Software +Foundation (ASF), sponsored by the Apache Incubator. + +Incubation is required of all newly accepted projects until a further review +indicates that the infrastructure, communications, and decision making process +have stabilized in a manner consistent with other successful ASF projects. + +While incubation status is not necessarily a reflection of the completeness +or stability of the code, it does indicate that the project has yet to be +fully endorsed by the ASF. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/a06335f8/MANIFEST.in ---------------------------------------------------------------------- diff --git a/MANIFEST.in b/MANIFEST.in index 6c79a3a..fe7df4c 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,5 @@ include requirements.txt include VERSION include LICENSE +include README.rst recursive-include examples * http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/a06335f8/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md deleted file mode 100644 index e534645..0000000 --- a/README.md +++ /dev/null @@ -1,201 +0,0 @@ -ARIA -==== - -[](https://travis-ci.org/apache/incubator-ariatosca) -[](https://ci.appveyor.com/project/ApacheSoftwareFoundation/incubator-ariatosca/history) -[](https://opensource.org/licenses/Apache-2.0) - - -[ARIA](http://ariatosca.org/) is a minimal TOSCA orchestrator, as well as a platform for building -TOSCA-based products. Its features can be accessed via a well-documented Python API. - -On its own, ARIA provides built-in tools for blueprint validation and for creating ready-to-run -service instances. - -ARIA adheres strictly and meticulously to the -[TOSCA Simple Profile v1.0 cos01 specification](http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html), -providing state-of-the-art validation at seven different levels: - -<ol start="0"> -<li>Platform errors. E.g. network, hardware, or even an internal bug in ARIA (let us know, - please!).</li> -<li>Syntax and format errors. E.g. non-compliant YAML, XML, JSON.</li> -<li>Field validation. E.g. assigning a string where an integer is expected, using a list instead of - a dict.</li> -<li>Relationships between fields within a type. This is "grammar" as it applies to rules for - setting the values of fields in relation to each other.</li> -<li>Relationships between types. E.g. referring to an unknown type, causing a type inheritance - loop.</li> -<li>Topology. These errors happen if requirements and capabilities cannot be matched in order to - assemble a valid topology.</li> -<li>External dependencies. These errors happen if requirement/capability matching fails due to - external resources missing, e.g. the lack of a valid virtual machine, API credentials, etc. - </li> -</ol> - -Validation errors include a plain English message and when relevant the exact location (file, row, -column) of the data the caused the error. - -The ARIA API documentation always links to the relevant section of the specification, and likewise -we provide an annotated version of the specification that links back to the API documentation. - - -Quick Start ------------ - -You need Python 2.6 or 2.7. Python 3+ is not currently supported. - -To install, we recommend using [pip](https://pip.pypa.io/) and a -[virtualenv](https://virtualenv.pypa.io/en/stable/). - -In Debian-based systems: - - sudo apt install python-setuptools - sudo -H easy_install pip - sudo -H pip install virtualenv - virtualenv env - -Or in Archlinux-based systems: - - pacman -S python2 python-setuptools python-pip - pip install virtualenv - virtualenv env -p $(type -p python2) - -To install the latest development snapshot of ARIA: - - . env/bin/activate - pip install git+http://git-wip-us.apache.org/repos/asf/incubator-ariatosca.git - -To test it, let's create a service instance from a TOSCA blueprint: - - aria parse blueprints/tosca/node-cellar/node-cellar.yaml - -You can also get it in JSON or YAML formats: - - aria parse blueprints/tosca/node-cellar/node-cellar.yaml --json - -Or get an overview of the relationship graph: - - aria parse blueprints/tosca/node-cellar/node-cellar.yaml --graph - -You can provide inputs as JSON, overriding default values provided in the blueprint - - aria parse blueprints/tosca/node-cellar/node-cellar.yaml --inputs='{"openstack_credential": {"user": "username"}}' - -Instead of providing them explicitly, you can also provide them in a file or URL, in either JSON or -YAML. If you do so, the value must end in ".json" or ".yaml": - - aria parse blueprints/tosca/node-cellar/node-cellar.yaml --inputs=blueprints/tosca/node-cellar/inputs.yaml - - -CLI ---- - -Though ARIA is fully exposed as an API, it also comes with a CLI tool to allow you to work from the -shell: - - aria parse blueprints/tosca/node-cellar/node-cellar.yaml instance - -The `parse` command supports the following directives to create variations of the default consumer -chain: - -* `presentation`: emits a colorized textual representation of the Python presentation classes - wrapping the blueprint. -* `model`: emits a colorized textual representation of the complete service model derived from the - validated blueprint. This includes all the node templates, with their requirements satisfied at - the level of relating to other node templates. -* `types`: emits a colorized textual representation of the type hierarchies. -* `instance`: **this is the default command**; emits a colorized textual representation of a - service instance instantiated from the service model. Here the node templates are each used to - create one or more nodes, with the appropriate relationships between them. Note that every time - you run this consumer, you will get a different set of node IDs. Use `--graph` to see just the - node relationship graph. - -For all these commands, you can also use `--json` or `--yaml` flags to emit in those formats. - -Additionally, The CLI tool lets you specify the complete classname of your own custom consumer to -chain at the end of the default consumer chain, after `instance`. - -Your custom consumer can be an entry point into a powerful TOSCA-based tool or application, such as -an orchestrator, a graphical modeling tool, etc. - - -Development ------------ - -Instead of installing with `pip`, it would be easier to work directly with the source files: - - pip install virtualenv - virtualenv env - . env/bin/activate - git clone http://git-wip-us.apache.org/repos/asf/incubator-ariatosca.git ariatosca - cd ariatosca - pip install -e . - -To run tests: - - pip install tox - tox - -Here's a quick example of using the API to parse YAML text into a service instance: - - from aria import install_aria_extensions - from aria.parser.consumption import ConsumptionContext, ConsumerChain, Read, Validate, Model, Instance - from aria.parser.loading import LiteralLocation - - def parse_text(payload, file_search_paths=[]): - context = ConsumptionContext() - context.presentation.location = LiteralLocation(payload) - context.loading.file_search_paths += file_search_paths - ConsumerChain(context, (Read, Validate, Model, Instance)).consume() - if not context.validation.dump_issues(): - return context.modeling.instance - return None - - install_aria_extensions() - - print parse_text(""" - tosca_definitions_version: tosca_simple_yaml_1_0 - topology_template: - node_templates: - MyNode: - type: tosca.nodes.Compute - """) - - -Parser API Architecture ------------------------ - -ARIA's parsing engine comprises individual "consumers" (in the `aria.parser.consumption` package) -that do things with blueprints. When chained together, each performs a different task, adds its own -validations, and can provide its own output. - -Parsing happens in five phases, represented in five packages: - -* `aria.parser.loading`: Loaders are used to read the TOSCA data, usually as text. For example - UriTextLoader will load text from URIs (including files). -* `aria.parser.reading`: Readers convert data from the loaders into agnostic raw data. For - example, `YamlReader` converts YAML text into Python dicts, lists, and primitives. -* `aria.parser.presentation`: Presenters wrap the agnostic raw data in a nice - Python facade (a "presentation") that makes it much easier to work with the data, including - utilities for validation, querying, etc. Note that presenters are _wrappers_: the agnostic raw - data is always maintained intact, and can always be accessed directly or written back to files. -* `aria.parser.modeling.model`: Here the topology is normalized into a coherent structure of - node templates, requirements, and capabilities. Types are inherited and properties are assigned. - The service model is a _new_ structure, which is not mapped to the YAML. In fact, it is possible - to generate the model programmatically, or from a DSL parser other than TOSCA. -* `aria.parser.modeling.instance`: The service instance is an instantiated service model. Node - templates turn into node instances (with unique IDs), and requirements are satisfied by matching - them to capabilities. This is where level 5 validation errors are detected (see above). - -The phases do not have to be used in order. Indeed, consumers do not have to be used at all: ARIA -can be used to _produce_ blueprints. For example, it is possible to fill in the -`aria.parser.presentation` classes programmatically, in Python, and then write the presentation -to a YAML file as compliant TOSCA. The same technique can be used to convert from one DSL (consume -it) to another (write it). - -The term "agnostic raw data" (ARD?) appears often in the documentation. It denotes data structures -comprising _only_ Python dicts, lists, and primitives, such that they can always be converted to and -from language-agnostic formats such as YAML, JSON, and XML. A considerable effort has been made to -conserve the agnostic raw data at all times. Thus, though ARIA makes good use of the dynamic power -of Python, you will _always_ be able to use ARIA with other systems. http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/a06335f8/README.rst ---------------------------------------------------------------------- diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..36dced9 --- /dev/null +++ b/README.rst @@ -0,0 +1,328 @@ +ARIA +==== + +|Build Status| |Appveyor Build Status| |License| |PyPI Release| |Python Versions| |Wheel| |Contributors| |Open Pull Requests| |Closed Pull Requests| + +`ARIA <http://ariatosca.org/>`__ is a minimal TOSCA orchestrator, as +well as a platform for building TOSCA-based products. Its features can +be accessed via a well-documented Python API. + +On its own, ARIA provides built-in tools for blueprint validation and +for creating ready-to-run service instances. + +ARIA adheres strictly and meticulously to the `TOSCA Simple Profile v1.0 +cos01 +specification <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html>`__, +providing state-of-the-art validation at seven different levels: + +.. raw:: html + + <ol start="0"> + +.. raw:: html + + <li> + +Platform errors. E.g. network, hardware, or even an internal bug in ARIA +(let us know, please!). + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +Syntax and format errors. E.g. non-compliant YAML, XML, JSON. + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +Field validation. E.g. assigning a string where an integer is expected, +using a list instead of a dict. + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +Relationships between fields within a type. This is "grammar" as it +applies to rules for setting the values of fields in relation to each +other. + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +Relationships between types. E.g. referring to an unknown type, causing +a type inheritance loop. + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +Topology. These errors happen if requirements and capabilities cannot be +matched in order to assemble a valid topology. + +.. raw:: html + + </li> + +.. raw:: html + + <li> + +External dependencies. These errors happen if requirement/capability +matching fails due to external resources missing, e.g. the lack of a +valid virtual machine, API credentials, etc. + +.. raw:: html + + </li> + +.. raw:: html + + </ol> + +Validation errors include a plain English message and when relevant the +exact location (file, row, column) of the data the caused the error. + +The ARIA API documentation always links to the relevant section of the +specification, and likewise we provide an annotated version of the +specification that links back to the API documentation. + +Quick Start +----------- + +You need Python 2.6 or 2.7. Python 3+ is not currently supported. + +To install, we recommend using `pip <https://pip.pypa.io/>`__ and a +`virtualenv <https://virtualenv.pypa.io/en/stable/>`__. + +In Debian-based systems: + +:: + + sudo apt install python-setuptools + sudo -H easy_install pip + sudo -H pip install virtualenv + virtualenv env + +Or in Archlinux-based systems: + +:: + + pacman -S python2 python-setuptools python-pip + pip install virtualenv + virtualenv env -p $(type -p python2) + +To install the latest development snapshot of ARIA: + +:: + + . env/bin/activate + pip install git+http://git-wip-us.apache.org/repos/asf/incubator-ariatosca.git + +To test it, let's create a service instance from a TOSCA blueprint: + +:: + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml + +You can also get it in JSON or YAML formats: + +:: + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml --json + +Or get an overview of the relationship graph: + +:: + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml --graph + +You can provide inputs as JSON, overriding default values provided in +the blueprint + +:: + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml --inputs='{"openstack_credential": {"user": "username"}}' + +Instead of providing them explicitly, you can also provide them in a +file or URL, in either JSON or YAML. If you do so, the value must end in +".json" or ".yaml": + +:: + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml --inputs=blueprints/tosca/node-cellar/inputs.yaml + +CLI +--- + +Though ARIA is fully exposed as an API, it also comes with a CLI tool to +allow you to work from the shell: + +:: + + aria parse blueprints/tosca/node-cellar/node-cellar.yaml instance + +The ``parse`` command supports the following directives to create +variations of the default consumer chain: + +- ``presentation``: emits a colorized textual representation of the + Python presentation classes wrapping the blueprint. +- ``model``: emits a colorized textual representation of the complete + service model derived from the validated blueprint. This includes all + the node templates, with their requirements satisfied at the level of + relating to other node templates. +- ``types``: emits a colorized textual representation of the type + hierarchies. +- ``instance``: **this is the default command**; emits a colorized + textual representation of a service instance instantiated from the + service model. Here the node templates are each used to create one or + more nodes, with the appropriate relationships between them. Note + that every time you run this consumer, you will get a different set + of node IDs. Use ``--graph`` to see just the node relationship graph. + +For all these commands, you can also use ``--json`` or ``--yaml`` flags +to emit in those formats. + +Additionally, The CLI tool lets you specify the complete classname of +your own custom consumer to chain at the end of the default consumer +chain, after ``instance``. + +Your custom consumer can be an entry point into a powerful TOSCA-based +tool or application, such as an orchestrator, a graphical modeling tool, +etc. + +Development +----------- + +Instead of installing with ``pip``, it would be easier to work directly +with the source files: + +:: + + pip install virtualenv + virtualenv env + . env/bin/activate + git clone http://git-wip-us.apache.org/repos/asf/incubator-ariatosca.git ariatosca + cd ariatosca + pip install -e . + +To run tests: + +:: + + pip install tox + tox + +Here's a quick example of using the API to parse YAML text into a +service instance: + +:: + + from aria import install_aria_extensions + from aria.parser.consumption import ConsumptionContext, ConsumerChain, Read, Validate, Model, Instance + from aria.parser.loading import LiteralLocation + + def parse_text(payload, file_search_paths=[]): + context = ConsumptionContext() + context.presentation.location = LiteralLocation(payload) + context.loading.file_search_paths += file_search_paths + ConsumerChain(context, (Read, Validate, Model, Instance)).consume() + if not context.validation.dump_issues(): + return context.modeling.instance + return None + + install_aria_extensions() + + print parse_text(""" + tosca_definitions_version: tosca_simple_yaml_1_0 + topology_template: + node_templates: + MyNode: + type: tosca.nodes.Compute + """) + +Parser API Architecture +----------------------- + +ARIA's parsing engine comprises individual "consumers" (in the +``aria.parser.consumption`` package) that do things with blueprints. +When chained together, each performs a different task, adds its own +validations, and can provide its own output. + +Parsing happens in five phases, represented in five packages: + +- ``aria.parser.loading``: Loaders are used to read the TOSCA data, + usually as text. For example UriTextLoader will load text from URIs + (including files). +- ``aria.parser.reading``: Readers convert data from the loaders into + agnostic raw data. For example, ``YamlReader`` converts YAML text + into Python dicts, lists, and primitives. +- ``aria.parser.presentation``: Presenters wrap the agnostic raw data + in a nice Python facade (a "presentation") that makes it much easier + to work with the data, including utilities for validation, querying, + etc. Note that presenters are *wrappers*: the agnostic raw data is + always maintained intact, and can always be accessed directly or + written back to files. +- ``aria.parser.modeling.model``: Here the topology is normalized into + a coherent structure of node templates, requirements, and + capabilities. Types are inherited and properties are assigned. The + service model is a *new* structure, which is not mapped to the YAML. + In fact, it is possible to generate the model programmatically, or + from a DSL parser other than TOSCA. +- ``aria.parser.modeling.instance``: The service instance is an + instantiated service model. Node templates turn into node instances + (with unique IDs), and requirements are satisfied by matching them to + capabilities. This is where level 5 validation errors are detected + (see above). + +The phases do not have to be used in order. Indeed, consumers do not +have to be used at all: ARIA can be used to *produce* blueprints. For +example, it is possible to fill in the ``aria.parser.presentation`` +classes programmatically, in Python, and then write the presentation to +a YAML file as compliant TOSCA. The same technique can be used to +convert from one DSL (consume it) to another (write it). + +The term "agnostic raw data" (ARD?) appears often in the documentation. +It denotes data structures comprising *only* Python dicts, lists, and +primitives, such that they can always be converted to and from +language-agnostic formats such as YAML, JSON, and XML. A considerable +effort has been made to conserve the agnostic raw data at all times. +Thus, though ARIA makes good use of the dynamic power of Python, you +will *always* be able to use ARIA with other systems. + +.. |Build Status| image:: https://travis-ci.org/apache/incubator-ariatosca.svg?branch=master + :target: https://travis-ci.org/apache/incubator-ariatosca +.. |Appveyor Build Status| image:: https://ci.appveyor.com/api/projects/status/ltv89jk63ahiu306?svg=true + :target: https://ci.appveyor.com/project/ApacheSoftwareFoundation/incubator-ariatosca/history +.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg + :target: https://opensource.org/licenses/Apache-2.0 +.. |PyPI Release| image:: https://img.shields.io/pypi/v/ariatosca.svg?style=plastic + :target: https://pypi.python.org/pypi/ariatosca +.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/ariatosca.svg?style=plastic +.. |Wheel| image:: https://img.shields.io/pypi/wheel/ariatosca.svg?style=plastic +.. |Contributors| image:: https://img.shields.io/github/contributors/apache/incubator-ariatosca.svg?style=plastic +.. |Open Pull Requests| image:: https://img.shields.io/github/issues-pr/apache/incubator-ariatosca.svg?style=plastic + :target: https://github.com/apache/incubator-ariatosca/pulls +.. |Closed Pull Requests| image:: https://img.shields.io/github/issues-pr-closed-raw/apache/incubator-ariatosca.svg?style=plastic + :target: https://github.com/apache/incubator-ariatosca/pulls?q=is%3Apr+is%3Aclosed http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/a06335f8/TODO.md ---------------------------------------------------------------------- diff --git a/TODO.md b/TODO.md deleted file mode 100644 index ab32cf7..0000000 --- a/TODO.md +++ /dev/null @@ -1,8 +0,0 @@ -- aria/parser/extension_tools.py:66: # todo: maybe add replace action and check in add that we don't replace... -- aria/parser/framework/elements/policies.py:128: # TODO: policies should be implemented according to TOSCA as generic types -- aria/parser/framework/elements/node_templates.py:42: # TODO: Capabilities should be implemented according to TOSCA as generic types -- aria/parser/framework/functions.py:25: # TODO: ugly huck for now..., sort the imports when you have time -- aria/parser/framework/parser.py:258: # TODO: need to clean up -- tests/parser/test_parser_api.py:430: # TODO: assert node-type's default and description values once -- tests/parser/test_parser_api.py:450: # TODO: assert type's default and description values once 'type' is -- tests/parser/test_parser_api.py:472: # TODO: assert type's default and description values once 'type' is http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/a06335f8/setup.py ---------------------------------------------------------------------- diff --git a/setup.py b/setup.py index d43ce91..8d5f463 100644 --- a/setup.py +++ b/setup.py @@ -39,6 +39,9 @@ root_dir = os.path.dirname(__file__) with open(os.path.join(root_dir, 'VERSION')) as version_file: __version__ = version_file.read().strip() +with open(os.path.join(root_dir, 'README.rst')) as readme: + long_description = readme.read() + install_requires = [] extras_require = {} @@ -106,10 +109,13 @@ setup( name=_PACKAGE_NAME, version=__version__, description='ARIA', + long_description=long_description, license='Apache License 2.0', author='aria', author_email='[email protected]', - url='http://ariatosca.org', + url='http://ariatosca.incubator.apache.org/', + download_url=( + 'https://dist.apache.org/repos/dist/release/incubator/ariatosca/' + __version__), classifiers=[ 'Development Status :: 4 - Beta', 'Environment :: Console',
