You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ariatosca.apache.org by ra...@apache.org on 2017/06/05 08:54:47 UTC
incubator-ariatosca git commit: readme conversion test
Repository: incubator-ariatosca
Updated Branches:
refs/heads/packaging [created] 653e1e940
readme conversion test
Project: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/commit/653e1e94
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/653e1e94
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/653e1e94
Branch: refs/heads/packaging
Commit: 653e1e940cebfdc82345b25a504765e48724f2cf
Parents: b6d3c43
Author: Ran Ziv <ra...@gigaspaces.com>
Authored: Mon Jun 5 11:54:40 2017 +0300
Committer: Ran Ziv <ra...@gigaspaces.com>
Committed: Mon Jun 5 11:54:40 2017 +0300
----------------------------------------------------------------------
README.md | 201 ----------------------------------------
README.rst | 281 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 281 insertions(+), 201 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/653e1e94/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/653e1e94/README.rst
----------------------------------------------------------------------
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..2fa21a5
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,281 @@
+ARIA
+====
+
+| |Build Status|
+| |Appveyor Build Status|
+| |License|
+
+| `ARIA`_ 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`_,
+| providing state-of-the-art validation at seven different levels:
+
+.. raw:: html
+
+ <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`_ and a
+| `virtualenv`_.
+
+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
+
+.. _ARIA: http://ariatosca.org/
+.. _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
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/en/stable/
+
+.. |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
+
+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.
\ No newline at end of file