Reliable and fast NGINX configuration file parser.
Project description
<p align="center">
<a href="https://github.com/nginxinc/crossplane"><img src="https://raw.githubusercontent.com/nginxinc/crossplane/master/ext/crossplane.png" width="40%" height="40%"></a>
</p>
<h1 align="center">crossplane</h1>
<h3 align="center">Reliable and fast NGINX configuration file parser and builder</h3>
<p align="center">
<a href="https://travis-ci.org/nginxinc/crossplane"><img src="https://img.shields.io/travis/nginxinc/crossplane/master.svg"></a>
<a href="https://github.com/nginxinc/crossplane/releases"><img src="https://img.shields.io/github/release/nginxinc/crossplane.svg"></a>
<a href="https://pypi.python.org/pypi/crossplane"><img src="https://img.shields.io/pypi/l/crossplane.svg"></a>
<a href="https://pypi.python.org/pypi/crossplane"><img src="https://img.shields.io/pypi/pyversions/crossplane.svg"></a>
</p>
- [Install](#install)
- [Command Line Interface](#command-line-interface)
- [crossplane parse](#crossplane-parse)
- [crossplane build](#crossplane-build)
- [crossplane lex](#crossplane-lex)
- [crossplane format](#crossplane-format)
- [crossplane minify](#crossplane-minify)
- [Python Module](#python-module)
- [crossplane.parse()](#crossplane.parse)
- [crossplane.build()](#crossplane.build)
- [crossplane.lex()](#crossplane.lex)
- [Other Languages](#other-languages)
- [Contributing](#contributing)
- [Types of Contributions](#types-of-contributions)
- [Get Started](#get-started)
- [Pull Request Guidelines](#pull-request-guidelines)
- [Tips](#tips)
## Install
You can install both the [Command Line
Interface](#command-line-interface) and [Python Module](#python-module)
via:
pip install crossplane
## Command Line Interface
```
usage: crossplane <command> [options]
various operations for nginx config files
optional arguments:
-h, --help show this help message and exit
commands:
parse parses a json payload for an nginx config
lex lexes tokens from an nginx config file
minify removes all whitespace from an nginx config
format formats an nginx config file
help show help for commands
```
### crossplane parse
This command will take a path to a main NGINX config file as input, then
parse the entire config into the schema defined below, and dumps the
entire thing as a JSON payload.
```
usage: crossplane parse [-h] [-o OUT] [-i NUM] [--ignore DIRECTIVES]
[--no-catch] [--tb-onerror] [--single-file]
[--include-comments] [--strict]
filename
parses a json payload for an nginx config
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
-i NUM, --indent NUM number of spaces to indent output
--ignore DIRECTIVES ignore directives (comma-separated)
--no-catch only collect first error in file
--tb-onerror include tracebacks in config errors
--combine use includes to create one single file
--single-file do not include other config files
--include-comments include comments in json
--strict raise errors for unknown directives
```
**Privacy and Security**
Since `crossplane` is usually used to create payloads that are sent to
different servers, it's important to keep security in mind. For that
reason, the `--ignore` option was added. It can be used to keep certain
sensitive directives out of the payload output entirely.
For example, we always the equivalent of this flag in the [NGINX Amplify
Agent](https://github.com/nginxinc/nginx-amplify-agent/) out of respect
for our users'
privacy:
--ignore=auth_basic_user_file,secure_link_secret,ssl_certificate_key,ssl_client_certificate,ssl_password_file,ssl_stapling_file,ssl_trusted_certificate
#### Schema
**Response Object**
```js
{
"status": String, // "ok" or "failed" if "errors" is not empty
"errors": Array, // aggregation of "errors" from Config objects
"config": Array // Array of Config objects
}
```
**Config Object**
```js
{
"file": String, // the full path of the config file
"status": String, // "ok" or "failed" if errors is not empty array
"errors": Array, // Array of Error objects
"parsed": Array // Array of Directive objects
}
```
**Directive Object**
```js
{
"directive": String, // the name of the directive
"line": Number, // integer line number the directive started on
"args": Array, // Array of String arguments
"includes": Array, // Array of integers (included iff this is an include directive)
"block": Array // Array of Directive Objects (included iff this is a block)
}
```
<div class="note">
<div class="admonition-title">
Note
</div>
If this is an `include` directive and the `--single-file` flag was not
used, an `"includes"` value will be used that holds an Array of indices
of the configs that are included by this directive.
If this is a block directive, a `"block"` value will be used that holds
an Array of more Directive Objects that define the block context.
</div>
**Error Object**
```js
{
"file": String, // the full path of the config file
"line": Number, // integer line number the directive that caused the error
"error": String, // the error message
"callback": Object // only included iff an "onerror" function was passed to parse()
}
```
<div class="note">
<div class="admonition-title">
Note
</div>
If the `--tb-onerror` flag was used by crossplane parse, `"callback"`
will contain a string that represents the traceback that the error
caused.
</div>
#### Example
The main NGINX config file is at `/etc/nginx/nginx.conf`:
```nginx
events {
worker_connections 1024;
}
http {
include conf.d/*.conf;
}
```
And this config file is at `/etc/nginx/conf.d/servers.conf`:
```nginx
server {
listen 8080;
location / {
try_files 'foo bar' baz;
}
}
server {
listen 8081;
location / {
return 200 'success!';
}
}
```
So then if you run this:
crossplane parse --indent=4 /etc/nginx/nginx.conf
The prettified JSON output would look like this:
```js
{
"status": "ok",
"errors": [],
"config": [
{
"file": "/etc/nginx/nginx.conf",
"status": "ok",
"errors": [],
"parsed": [
{
"directive": "events",
"line": 1,
"args": [],
"block": [
{
"directive": "worker_connections",
"line": 2,
"args": [
"1024"
]
}
]
},
{
"directive": "http",
"line": 5,
"args": [],
"block": [
{
"directive": "include",
"line": 6,
"args": [
"conf.d/*.conf"
],
"includes": [
1
]
}
]
}
]
},
{
"file": "/etc/nginx/conf.d/servers.conf",
"status": "ok",
"errors": [],
"parsed": [
{
"directive": "server",
"line": 1,
"args": [],
"block": [
{
"directive": "listen",
"line": 2,
"args": [
"8080"
]
},
{
"directive": "location",
"line": 3,
"args": [
"/"
],
"block": [
{
"directive": "try_files",
"line": 4,
"args": [
"foo bar",
"baz"
]
}
]
}
]
},
{
"directive": "server",
"line": 8,
"args": [],
"block": [
{
"directive": "listen",
"line": 9,
"args": [
"8081"
]
},
{
"directive": "location",
"line": 10,
"args": [
"/"
],
"block": [
{
"directive": "return",
"line": 11,
"args": [
"200",
"success!"
]
}
]
}
]
}
]
}
]
}
```
#### crossplane parse (advanced)
This tool uses two flags that can change how `crossplane` handles
errors.
The first, `--no-catch`, can be used if you'd prefer that crossplane
quit parsing after the first error it finds.
The second, `--tb-onerror`, will add a `"callback"` key to all error
objects in the JSON output, each containing a string representation of
the traceback that would have been raised by the parser if the exception
had not been caught. This can be useful for logging purposes.
### crossplane build
This command will take a path to a file as input. The file should
contain a JSON representation of an NGINX config that has the structure
defined above. Saving and using the output from `crossplane parse` to
rebuild your config files should not cause any differences in content
except for the formatting.
```
usage: crossplane build [-h] [-d PATH] [-f] [-i NUM | -t] [--no-headers]
[--stdout] [-v]
filename
builds an nginx config from a json payload
positional arguments:
filename the file with the config payload
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
-d PATH, --dir PATH the base directory to build in
-f, --force overwrite existing files
-i NUM, --indent NUM number of spaces to indent output
-t, --tabs indent with tabs instead of spaces
--no-headers do not write header to configs
--stdout write configs to stdout instead
```
### crossplane lex
This command takes an NGINX config file, splits it into tokens by
removing whitespace and comments, and dumps the list of tokens as a JSON
array.
```
usage: crossplane lex [-h] [-o OUT] [-i NUM] [-n] filename
lexes tokens from an nginx config file
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
-i NUM, --indent NUM number of spaces to indent output
-n, --line-numbers include line numbers in json payload
```
#### Example
Passing in this NGINX config file at `/etc/nginx/nginx.conf`:
```nginx
events {
worker_connections 1024;
}
http {
include conf.d/*.conf;
}
```
By running:
crossplane lex /etc/nginx/nginx.conf
Will result in this JSON
output:
```js
["events","{","worker_connections","1024",";","}","http","{","include","conf.d/*.conf",";","}"]
```
However, if you decide to use the `--line-numbers` flag, your output
will look
like:
```js
[["events",1],["{",1],["worker_connections",2],["1024",2],[";",2],["}",3],["http",5],["{",5],["include",6],["conf.d/*.conf",6],[";",6],["}",7]]
```
### crossplane format
This is a quick and dirty tool that uses [crossplane
parse](#crossplane-parse) internally to format an NGINX config file.
Currently it removes all blank lines and comments, but this may get
improved more in the future if there's demand for it. As of now, it
serves the purpose of demonstrating what you can do with `crossplane`'s
parsing abilities.
```
usage: crossplane format [-h] [-o OUT] [-i NUM | -t] filename
formats an nginx config file
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
-i NUM, --indent NUM number of spaces to indent output
-t, --tabs indent with tabs instead of spaces
```
### crossplane minify
This is a simple and fun little tool that uses [crossplane
lex](#crossplane-lex) internally to remove as much whitespace from an
NGINX config file as possible without affecting what it does. It can't
imagine it will have much of a use to most people, but it demonstrates
the kinds of things you can do with `crossplane`'s lexing abilities.
```
usage: crossplane minify [-h] [-o OUT] filename
removes all whitespace from an nginx config
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
```
## Python Module
In addition to the command line tool, you can import `crossplane` as a
python module. There are two basic functions that the module will
provide you: `parse` and `lex`.
### crossplane.parse()
```python
import crossplane
payload = crossplane.parse('/etc/nginx/nginx.conf')
```
This will return the same payload as described in the [crossplane
parse](#crossplane-parse) section, except it will be Python dicts and
not one giant JSON string.
### crossplane.build()
```python
import crossplane
config = crossplane.build(
[{
"directive": "events",
"args": [],
"block": [{
"directive": "worker_connections",
"args": ["1024"]
}]
}]
)
```
This will return a single string that contains an entire NGINX config
file.
### crossplane.lex()
```python
import crossplane
tokens = crossplane.lex('/etc/nginx/nginx.conf')
```
`crossplane.lex` generates 2-tuples. Inserting these pairs into a list
will result in a long list similar to what you can see in the
[crossplane lex](#crossplane-lex) section when the `--line-numbers` flag
is used, except it will obviously be a Python list of tuples and not one
giant JSON string.
## Other Languages
- Ruby port by [@gdanko](https://github.com/gdanko):
<https://github.com/gdanko/crossplane>
## Contributing
Contributions are welcome, and they are greatly appreciated\! Every
little bit helps, and credit will always be given.
You can contribute in many ways:
### Types of Contributions
#### Report Bugs
Report bugs at <https://github.com/nginxinc/crossplane/issues>.
If you are reporting a bug, please include:
- Your operating system name and version.
- Any details about your local setup that might be helpful in
troubleshooting.
- Detailed steps to reproduce the bug.
#### Fix Bugs
Look through the GitHub issues for bugs. Anything tagged with "bug" is
open to whoever wants to implement it.
#### Implement Features
Look through the GitHub issues for features. Anything tagged with
"feature" is open to whoever wants to implement it.
#### Write Documentation
crossplane could always use more documentation, whether as part of the
official crossplane docs, in docstrings, or even on the web in blog
posts, articles, and such.
#### Submit Feedback
The best way to send feedback is to file an issue at
<https://github.com/nginxinc/crossplane/issues>.
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to
implement.
- Remember that this is a volunteer-driven project, and that
contributions are welcome :)
### Get Started
Ready to contribute? Here's how to set up crossplane for local
development.
1. [Fork](https://github.com/nginxinc/crossplane/fork) the crossplane
repo on GitHub.
2. Clone your fork locally:
git clone git@github.com:your_name_here/crossplane.git
3. Create a branch for local development:
git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
4. When you're done making changes, check that your changes pass style
and unit tests, including testing other Python versions with tox:
tox
To get tox, just pip install it.
5. Commit your changes and push your branch to GitHub:
git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature
6. Submit a pull request through the GitHub website.
### Pull Request Guidelines
Before you submit a pull request, check that it meets these guidelines:
1. The pull request should include tests.
2. The pull request should work for CPython 2.6, 2.7, 3.3, 3.4, 3.5,
3.6, and 3.7 and for PyPy. Check
<https://travis-ci.org/nginxinc/crossplane> under pull requests for
active pull requests or run the `tox` command and make sure that the
tests pass for all supported Python versions.
3. Make sure to add yourself to the Contributors list in AUTHORS.rst :)
### Tips
To run a subset of tests:
tox -e <env> -- tests/<file>[::test]
To run all the test environments in *parallel* (you need to `pip install
detox`):
detox
<a href="https://github.com/nginxinc/crossplane"><img src="https://raw.githubusercontent.com/nginxinc/crossplane/master/ext/crossplane.png" width="40%" height="40%"></a>
</p>
<h1 align="center">crossplane</h1>
<h3 align="center">Reliable and fast NGINX configuration file parser and builder</h3>
<p align="center">
<a href="https://travis-ci.org/nginxinc/crossplane"><img src="https://img.shields.io/travis/nginxinc/crossplane/master.svg"></a>
<a href="https://github.com/nginxinc/crossplane/releases"><img src="https://img.shields.io/github/release/nginxinc/crossplane.svg"></a>
<a href="https://pypi.python.org/pypi/crossplane"><img src="https://img.shields.io/pypi/l/crossplane.svg"></a>
<a href="https://pypi.python.org/pypi/crossplane"><img src="https://img.shields.io/pypi/pyversions/crossplane.svg"></a>
</p>
- [Install](#install)
- [Command Line Interface](#command-line-interface)
- [crossplane parse](#crossplane-parse)
- [crossplane build](#crossplane-build)
- [crossplane lex](#crossplane-lex)
- [crossplane format](#crossplane-format)
- [crossplane minify](#crossplane-minify)
- [Python Module](#python-module)
- [crossplane.parse()](#crossplane.parse)
- [crossplane.build()](#crossplane.build)
- [crossplane.lex()](#crossplane.lex)
- [Other Languages](#other-languages)
- [Contributing](#contributing)
- [Types of Contributions](#types-of-contributions)
- [Get Started](#get-started)
- [Pull Request Guidelines](#pull-request-guidelines)
- [Tips](#tips)
## Install
You can install both the [Command Line
Interface](#command-line-interface) and [Python Module](#python-module)
via:
pip install crossplane
## Command Line Interface
```
usage: crossplane <command> [options]
various operations for nginx config files
optional arguments:
-h, --help show this help message and exit
commands:
parse parses a json payload for an nginx config
lex lexes tokens from an nginx config file
minify removes all whitespace from an nginx config
format formats an nginx config file
help show help for commands
```
### crossplane parse
This command will take a path to a main NGINX config file as input, then
parse the entire config into the schema defined below, and dumps the
entire thing as a JSON payload.
```
usage: crossplane parse [-h] [-o OUT] [-i NUM] [--ignore DIRECTIVES]
[--no-catch] [--tb-onerror] [--single-file]
[--include-comments] [--strict]
filename
parses a json payload for an nginx config
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
-i NUM, --indent NUM number of spaces to indent output
--ignore DIRECTIVES ignore directives (comma-separated)
--no-catch only collect first error in file
--tb-onerror include tracebacks in config errors
--combine use includes to create one single file
--single-file do not include other config files
--include-comments include comments in json
--strict raise errors for unknown directives
```
**Privacy and Security**
Since `crossplane` is usually used to create payloads that are sent to
different servers, it's important to keep security in mind. For that
reason, the `--ignore` option was added. It can be used to keep certain
sensitive directives out of the payload output entirely.
For example, we always the equivalent of this flag in the [NGINX Amplify
Agent](https://github.com/nginxinc/nginx-amplify-agent/) out of respect
for our users'
privacy:
--ignore=auth_basic_user_file,secure_link_secret,ssl_certificate_key,ssl_client_certificate,ssl_password_file,ssl_stapling_file,ssl_trusted_certificate
#### Schema
**Response Object**
```js
{
"status": String, // "ok" or "failed" if "errors" is not empty
"errors": Array, // aggregation of "errors" from Config objects
"config": Array // Array of Config objects
}
```
**Config Object**
```js
{
"file": String, // the full path of the config file
"status": String, // "ok" or "failed" if errors is not empty array
"errors": Array, // Array of Error objects
"parsed": Array // Array of Directive objects
}
```
**Directive Object**
```js
{
"directive": String, // the name of the directive
"line": Number, // integer line number the directive started on
"args": Array, // Array of String arguments
"includes": Array, // Array of integers (included iff this is an include directive)
"block": Array // Array of Directive Objects (included iff this is a block)
}
```
<div class="note">
<div class="admonition-title">
Note
</div>
If this is an `include` directive and the `--single-file` flag was not
used, an `"includes"` value will be used that holds an Array of indices
of the configs that are included by this directive.
If this is a block directive, a `"block"` value will be used that holds
an Array of more Directive Objects that define the block context.
</div>
**Error Object**
```js
{
"file": String, // the full path of the config file
"line": Number, // integer line number the directive that caused the error
"error": String, // the error message
"callback": Object // only included iff an "onerror" function was passed to parse()
}
```
<div class="note">
<div class="admonition-title">
Note
</div>
If the `--tb-onerror` flag was used by crossplane parse, `"callback"`
will contain a string that represents the traceback that the error
caused.
</div>
#### Example
The main NGINX config file is at `/etc/nginx/nginx.conf`:
```nginx
events {
worker_connections 1024;
}
http {
include conf.d/*.conf;
}
```
And this config file is at `/etc/nginx/conf.d/servers.conf`:
```nginx
server {
listen 8080;
location / {
try_files 'foo bar' baz;
}
}
server {
listen 8081;
location / {
return 200 'success!';
}
}
```
So then if you run this:
crossplane parse --indent=4 /etc/nginx/nginx.conf
The prettified JSON output would look like this:
```js
{
"status": "ok",
"errors": [],
"config": [
{
"file": "/etc/nginx/nginx.conf",
"status": "ok",
"errors": [],
"parsed": [
{
"directive": "events",
"line": 1,
"args": [],
"block": [
{
"directive": "worker_connections",
"line": 2,
"args": [
"1024"
]
}
]
},
{
"directive": "http",
"line": 5,
"args": [],
"block": [
{
"directive": "include",
"line": 6,
"args": [
"conf.d/*.conf"
],
"includes": [
1
]
}
]
}
]
},
{
"file": "/etc/nginx/conf.d/servers.conf",
"status": "ok",
"errors": [],
"parsed": [
{
"directive": "server",
"line": 1,
"args": [],
"block": [
{
"directive": "listen",
"line": 2,
"args": [
"8080"
]
},
{
"directive": "location",
"line": 3,
"args": [
"/"
],
"block": [
{
"directive": "try_files",
"line": 4,
"args": [
"foo bar",
"baz"
]
}
]
}
]
},
{
"directive": "server",
"line": 8,
"args": [],
"block": [
{
"directive": "listen",
"line": 9,
"args": [
"8081"
]
},
{
"directive": "location",
"line": 10,
"args": [
"/"
],
"block": [
{
"directive": "return",
"line": 11,
"args": [
"200",
"success!"
]
}
]
}
]
}
]
}
]
}
```
#### crossplane parse (advanced)
This tool uses two flags that can change how `crossplane` handles
errors.
The first, `--no-catch`, can be used if you'd prefer that crossplane
quit parsing after the first error it finds.
The second, `--tb-onerror`, will add a `"callback"` key to all error
objects in the JSON output, each containing a string representation of
the traceback that would have been raised by the parser if the exception
had not been caught. This can be useful for logging purposes.
### crossplane build
This command will take a path to a file as input. The file should
contain a JSON representation of an NGINX config that has the structure
defined above. Saving and using the output from `crossplane parse` to
rebuild your config files should not cause any differences in content
except for the formatting.
```
usage: crossplane build [-h] [-d PATH] [-f] [-i NUM | -t] [--no-headers]
[--stdout] [-v]
filename
builds an nginx config from a json payload
positional arguments:
filename the file with the config payload
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
-d PATH, --dir PATH the base directory to build in
-f, --force overwrite existing files
-i NUM, --indent NUM number of spaces to indent output
-t, --tabs indent with tabs instead of spaces
--no-headers do not write header to configs
--stdout write configs to stdout instead
```
### crossplane lex
This command takes an NGINX config file, splits it into tokens by
removing whitespace and comments, and dumps the list of tokens as a JSON
array.
```
usage: crossplane lex [-h] [-o OUT] [-i NUM] [-n] filename
lexes tokens from an nginx config file
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
-i NUM, --indent NUM number of spaces to indent output
-n, --line-numbers include line numbers in json payload
```
#### Example
Passing in this NGINX config file at `/etc/nginx/nginx.conf`:
```nginx
events {
worker_connections 1024;
}
http {
include conf.d/*.conf;
}
```
By running:
crossplane lex /etc/nginx/nginx.conf
Will result in this JSON
output:
```js
["events","{","worker_connections","1024",";","}","http","{","include","conf.d/*.conf",";","}"]
```
However, if you decide to use the `--line-numbers` flag, your output
will look
like:
```js
[["events",1],["{",1],["worker_connections",2],["1024",2],[";",2],["}",3],["http",5],["{",5],["include",6],["conf.d/*.conf",6],[";",6],["}",7]]
```
### crossplane format
This is a quick and dirty tool that uses [crossplane
parse](#crossplane-parse) internally to format an NGINX config file.
Currently it removes all blank lines and comments, but this may get
improved more in the future if there's demand for it. As of now, it
serves the purpose of demonstrating what you can do with `crossplane`'s
parsing abilities.
```
usage: crossplane format [-h] [-o OUT] [-i NUM | -t] filename
formats an nginx config file
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
-i NUM, --indent NUM number of spaces to indent output
-t, --tabs indent with tabs instead of spaces
```
### crossplane minify
This is a simple and fun little tool that uses [crossplane
lex](#crossplane-lex) internally to remove as much whitespace from an
NGINX config file as possible without affecting what it does. It can't
imagine it will have much of a use to most people, but it demonstrates
the kinds of things you can do with `crossplane`'s lexing abilities.
```
usage: crossplane minify [-h] [-o OUT] filename
removes all whitespace from an nginx config
positional arguments:
filename the nginx config file
optional arguments:
-h, --help show this help message and exit
-o OUT, --out OUT write output to a file
```
## Python Module
In addition to the command line tool, you can import `crossplane` as a
python module. There are two basic functions that the module will
provide you: `parse` and `lex`.
### crossplane.parse()
```python
import crossplane
payload = crossplane.parse('/etc/nginx/nginx.conf')
```
This will return the same payload as described in the [crossplane
parse](#crossplane-parse) section, except it will be Python dicts and
not one giant JSON string.
### crossplane.build()
```python
import crossplane
config = crossplane.build(
[{
"directive": "events",
"args": [],
"block": [{
"directive": "worker_connections",
"args": ["1024"]
}]
}]
)
```
This will return a single string that contains an entire NGINX config
file.
### crossplane.lex()
```python
import crossplane
tokens = crossplane.lex('/etc/nginx/nginx.conf')
```
`crossplane.lex` generates 2-tuples. Inserting these pairs into a list
will result in a long list similar to what you can see in the
[crossplane lex](#crossplane-lex) section when the `--line-numbers` flag
is used, except it will obviously be a Python list of tuples and not one
giant JSON string.
## Other Languages
- Ruby port by [@gdanko](https://github.com/gdanko):
<https://github.com/gdanko/crossplane>
## Contributing
Contributions are welcome, and they are greatly appreciated\! Every
little bit helps, and credit will always be given.
You can contribute in many ways:
### Types of Contributions
#### Report Bugs
Report bugs at <https://github.com/nginxinc/crossplane/issues>.
If you are reporting a bug, please include:
- Your operating system name and version.
- Any details about your local setup that might be helpful in
troubleshooting.
- Detailed steps to reproduce the bug.
#### Fix Bugs
Look through the GitHub issues for bugs. Anything tagged with "bug" is
open to whoever wants to implement it.
#### Implement Features
Look through the GitHub issues for features. Anything tagged with
"feature" is open to whoever wants to implement it.
#### Write Documentation
crossplane could always use more documentation, whether as part of the
official crossplane docs, in docstrings, or even on the web in blog
posts, articles, and such.
#### Submit Feedback
The best way to send feedback is to file an issue at
<https://github.com/nginxinc/crossplane/issues>.
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to
implement.
- Remember that this is a volunteer-driven project, and that
contributions are welcome :)
### Get Started
Ready to contribute? Here's how to set up crossplane for local
development.
1. [Fork](https://github.com/nginxinc/crossplane/fork) the crossplane
repo on GitHub.
2. Clone your fork locally:
git clone git@github.com:your_name_here/crossplane.git
3. Create a branch for local development:
git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
4. When you're done making changes, check that your changes pass style
and unit tests, including testing other Python versions with tox:
tox
To get tox, just pip install it.
5. Commit your changes and push your branch to GitHub:
git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature
6. Submit a pull request through the GitHub website.
### Pull Request Guidelines
Before you submit a pull request, check that it meets these guidelines:
1. The pull request should include tests.
2. The pull request should work for CPython 2.6, 2.7, 3.3, 3.4, 3.5,
3.6, and 3.7 and for PyPy. Check
<https://travis-ci.org/nginxinc/crossplane> under pull requests for
active pull requests or run the `tox` command and make sure that the
tests pass for all supported Python versions.
3. Make sure to add yourself to the Contributors list in AUTHORS.rst :)
### Tips
To run a subset of tests:
tox -e <env> -- tests/<file>[::test]
To run all the test environments in *parallel* (you need to `pip install
detox`):
detox
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
crossplane-0.4.7.tar.gz
(41.4 kB
view hashes)
Built Distribution
Close
Hashes for crossplane-0.4.7-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 31869ff29de849c04194e99a2b791e426a76473c7c246cec7d8dcda1a4cb7ac6 |
|
MD5 | ecc525444be39891948fd2b7f4a73e0e |
|
BLAKE2b-256 | 0dd257a61cbddabcac40c4dd252667e3ecdbb97e0e9461a4367649647d544d02 |