Skip to content

Commit

Permalink
README update: Codacy integration
Browse files Browse the repository at this point in the history
  • Loading branch information
pavel-kirienko committed Mar 27, 2019
1 parent f4dd436 commit 84a2769
Showing 1 changed file with 37 additions and 37 deletions.
74 changes: 37 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ PyDSDL
[![Travis CI](https://travis-ci.org/UAVCAN/pydsdl.svg?branch=master)](https://travis-ci.org/UAVCAN/pydsdl)
[![Coverage Status](https://coveralls.io/repos/github/UAVCAN/pydsdl/badge.svg)](https://coveralls.io/github/UAVCAN/pydsdl)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pydsdl.svg)](https://test.pypi.org/project/pydsdl/)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/a0fdcbe8332a46399a2da90f97900e78)](https://www.codacy.com/app/UAVCAN/pydsdl)
[![Forum](https://img.shields.io/discourse/https/forum.uavcan.org/users.svg)](https://forum.uavcan.org)


**PyDSDL is a [UAVCAN](https://uavcan.org) DSDL compiler frontend implemented in Python.**

PyDSDL supports all DSDL features defined in the UAVCAN specification,
Expand All @@ -29,8 +29,8 @@ Make sure that it works by importing it: `import pydsdl`.
The library is bundled with the following third-party software libraries (by virtue of being bundled,
they need not be installed by the user):

- [Parsimonious](https://github.com/erikrose/parsimonious) by Erik Rose, MIT license.
- [Six](https://github.com/benjaminp/six) by Benjamin Peterson, MIT license; needed for Parsimonious.
- [Parsimonious](https://github.com/erikrose/parsimonious) by Erik Rose, MIT license.
- [Six](https://github.com/benjaminp/six) by Benjamin Peterson, MIT license; needed for Parsimonious.


## Library API
Expand Down Expand Up @@ -64,22 +64,22 @@ DSDL data types are modeled through the following Python types.
The user application should not instantiate them directly.
All of them share the same common ancestor `DataType` and the naming pattern `pydsdl.*Type`:

* `DataType` - the root class; it also inherits from `pydsdl.Any`, since DSDL types are also values.
* `VoidType` - e.g., `void16`
* `PrimitiveType`
* `BooleanType` - e.g., `bool`
* `ArithmeticType`
* `FloatType` - e.g., `truncated float16`
* `IntegerType`
* `SignedIntegerType` - e.g., `int16`
* `UnsignedIntegerType` - e.g., `saturated uint32`
* `ArrayType`
* `FixedLengthArrayType` - e.g., `uint8[256]`
* `VariableLengthArrayType` - e.g., `uint8[<256]`
* `CompoundType` - see below.
* `UnionType` - message types or nested structures.
* `StructureType` - message types or nested structures.
* `ServiceType` - service types, not serializable.
- `DataType` - the root class; it also inherits from `pydsdl.Any`, since DSDL types are also values.
- `VoidType` - e.g., `void16`
- `PrimitiveType`
- `BooleanType` - e.g., `bool`
- `ArithmeticType`
- `FloatType` - e.g., `truncated float16`
- `IntegerType`
- `SignedIntegerType` - e.g., `int16`
- `UnsignedIntegerType` - e.g., `saturated uint32`
- `ArrayType`
- `FixedLengthArrayType` - e.g., `uint8[256]`
- `VariableLengthArrayType` - e.g., `uint8[<256]`
- `CompoundType` - see below.
- `UnionType` - message types or nested structures.
- `StructureType` - message types or nested structures.
- `ServiceType` - service types, not serializable.

The type `CompoundType` is the most interesting one, as it represents actual DSDL definitions upon their interpretation.
The following are its most important properties, their semantics should be obvious enough from their names:
Expand All @@ -92,25 +92,25 @@ response structure of the service type, respectively.
Every data type (i.e., the `DataType` root class) has the following public attributes
(although they raise `TypeError` when used against an instance of `ServiceType`):

* `bit_length_range: Tuple[int, int]` - returns a named tuple containing `min:int` and `max:int`, in bits,
- `bit_length_range: Tuple[int, int]` - returns a named tuple containing `min:int` and `max:int`, in bits,
which represent the minimum and the maximum possible bit length of an encoded representation.
* `compute_bit_length_values() -> Set[int]` - this function performs a bit length combination analysis on
- `compute_bit_length_values() -> Set[int]` - this function performs a bit length combination analysis on
the data type and returns a full set of bit lengths of all possible valid encoded representations of the data type.
Due to the involved computations, the function can be expensive to invoke, so use with care.

Instances of `CompoundType` (and its derivatives) contain *attributes*.
Per the specification, an attribute can be a field or a constant.
The corresponding data model is shown below:

* `Attribute` - the root class.
* `Field` - e.g., `uavcan.node.Heartbeat.1.0 status`
* `PaddingField` - e.g., `void5` (the name is always empty)
* `Constant` - e.g., `uint16 VALUE = 0x1234`.
- `Attribute` - the root class.
- `Field` - e.g., `uavcan.node.Heartbeat.1.0 status`
- `PaddingField` - e.g., `void5` (the name is always empty)
- `Constant` - e.g., `uint16 VALUE = 0x1234`.

The root class `Attribute` exposes the following public properties:

* `data_type: pydsdl.DataType` - the data type of the attribute.
* `name: str` - the name of the attribute; always empty for padding fields.
- `data_type: pydsdl.DataType` - the data type of the attribute.
- `name: str` - the name of the attribute; always empty for padding fields.

The type `Constant` also has a property `value: pydsdl.Any`, which returns the value of the constant
as a DSDL expression value. Read below for details.
Expand All @@ -119,11 +119,11 @@ as a DSDL expression value. Read below for details.

The root exception types follow the naming pattern `pydsdl.*Error`, they are used to represent errors:

* `FrontendError` - contains properties `path:str` and `line:int`, both of which are optional,
- `FrontendError` - contains properties `path:str` and `line:int`, both of which are optional,
which (if set) point out to the exact location where the error has occurred: the path of the DSDL file and
the line number within the file (starting from one). If line is set, path is also set.
* `InternalError` - an error that occurred within the front end itself, at no fault of the processed definition.
* `InvalidDefinitionError` - represents a problem with the processed definition.
- `InternalError` - an error that occurred within the front end itself, at no fault of the processed definition.
- `InvalidDefinitionError` - represents a problem with the processed definition.
This type is inherited by a dozen of specialized error exception classes; however, the class hierarchy beneath
this type is unstable and should not be used by the application directly.

Expand All @@ -140,15 +140,15 @@ Constant expression values are represented through Python types rooted under `py
DSDL types are also constant values, so `pydsdl.DataType` (the root of the type model) inherits from `pydsdl.Any`.
The class hierarchy is as follows:

* `Any` - has a class property (i.e., "static" property) `TYPE_NAME: str`, which contains the DSDL name of the type.
* `Primitive` - primitive values; has virtual property `native_value` which yields an appropriate Python-native
- `Any` - has a class property (i.e., "static" property) `TYPE_NAME: str`, which contains the DSDL name of the type.
- `Primitive` - primitive values; has virtual property `native_value` which yields an appropriate Python-native
representation of the contained value.
* `Boolean` - a Boolean constant; has `native_value: bool`.
* `Rational` - real value approximation; has `native_value: fractions.Fraction`, `is_integer() -> bool`, and
- `Boolean` - a Boolean constant; has `native_value: bool`.
- `Rational` - real value approximation; has `native_value: fractions.Fraction`, `is_integer() -> bool`, and
`as_native_integer() -> int` (which throws if the contained number is not an integer).
* `String` - a Unicode string; has `native_value: str`.
* `Container` - generic container; has `element_type: Type[Any]` and is iterable.
* `Set` - a DSDL constant homogeneous set.
- `String` - a Unicode string; has `native_value: str`.
- `Container` - generic container; has `element_type: Type[Any]` and is iterable.
- `Set` - a DSDL constant homogeneous set.

## Usage example

Expand Down

0 comments on commit 84a2769

Please sign in to comment.