crossplane

library0.5.8pypypi✓ verified 25d ago

Crossplane is a Python library and command-line interface (CLI) tool for reliably and quickly parsing and building NGINX configuration files. It handles includes, variables, and common NGINX directives, providing a structured JSON representation of the configuration. The current version is 0.5.8, with releases occurring periodically to update NGINX directive definitions and fix bugs.

devops http-networking

pip install crossplane

github ↗package ↗

INSTALL

IMPORT

SIG · CROSSPLANE

crossplane

devopspythonv0.5.8

Install

1.6s avg

Import

71ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.8 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.068s · 18.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.074s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ from crossplane import parse

Used to parse an NGINX configuration file into a Python object/JSON structure.

build

✓ from crossplane import build

Used to build an NGINX configuration string from a parsed Python object/JSON structure.

lex

✓ from crossplane import lex

Used to tokenize an NGINX configuration file.

This quickstart demonstrates how to use `crossplane.parse()` to transform an NGINX configuration string into a structured Python object (often represented as JSON), and then `crossplane.build()` to convert it back into an NGINX configuration string. This allows for programmatic inspection and modification of NGINX configurations.

from crossplane import parse, build import json nginx_config_content = ''' user nginx; worker_processes 1; error_log /var/log/nginx/error.log warn; pid /var/run/nginx.pid; events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for"; access_log /var/log/nginx/access.log main; sendfile on; #tcp_nopush on; keepalive_timeout 65; #gzip on; server { listen 80; server_name localhost; location / { root /usr/share/nginx/html; index index.html index.htm; } error_page 500 502 503 504 /50x.html; location = /50x.html { root /usr/share/nginx/html; } } } ''' # Parse the NGINX configuration string parsed_config = parse(nginx_config_content, filename='nginx.conf') # Print the parsed structure (JSON representation) print("Parsed NGINX Config (JSON):") print(json.dumps(parsed_config, indent=2)) # Example of accessing parsed data if parsed_config['status'] == 'ok' and parsed_config['config']: first_file_config = parsed_config['config'][0]['parsed'] print(f"\nWorker processes: {first_file_config[1]['args'][0]}") # Build the config back into a string (simplified, without complex includes) # For real file paths, ensure the 'filename' parameter matches where crossplane expects to find included files. rebuilt_config = build(parsed_config) print("\nRebuilt NGINX Config:") print(rebuilt_config)

crossplane --version

Debug

Known issues

breakingThe behavior of `crossplane format` (and potentially `crossplane.format` function) changed significantly in v0.5.2. Prior to this version, the formatter would remove all comments from the NGINX configuration. From v0.5.2 onwards, it preserves comments.

fix

If your automation relied on comment removal during formatting, update your logic or use an older version. Otherwise, be aware that formatting output will now include comments.

affects: <0.5.2

gotchaParsing of non-Unicode (non-UTF-8) NGINX configurations was improved in version 0.5.8. Older versions might misinterpret or fail to parse configurations containing non-UTF-8 characters, especially those using locale-specific encodings.

fix

Upgrade to crossplane v0.5.8 or newer for robust handling of diverse character encodings in NGINX configurations.

affects: <0.5.8

gotchaIn versions prior to 0.5.1, comments placed between arguments of an NGINX directive were incorrectly parsed as arguments themselves. This could lead to malformed parsed structures.

fix

Upgrade to crossplane v0.5.1 or newer. If on an older version, ensure no comments are placed within a directive's argument list.

affects: <0.5.1

gotchaThe `crossplane parse` CLI command (and likely the Python `parse` function) supports a `--strict` flag to raise errors for unknown NGINX directives. By default, it might be more lenient, which could hide misconfigurations if not explicitly enabled.

fix

Consider using the `--strict` flag (or its Python API equivalent if available) in critical parsing operations to enforce stricter validation of NGINX configuration syntax against known directives.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'crossplane'

The `crossplane` Python package is not installed in the environment where the script is being run, or there is a typo in the import statement.

fix

Install the package using pip: `pip install crossplane`

crossplane: command not found

The `crossplane` command-line interface (CLI) tool is not installed, or its installation location is not included in the system's PATH environment variable.

fix

Ensure the package is installed via `pip install crossplane`. If installed, verify that the Python script directory (often `~/.local/bin` or a virtual environment's `bin` directory) is in your system's PATH. You may also be able to run it using `python -m crossplane`.

TypeError: string indices must be integers, not str

This error occurs when attempting to access elements of a dictionary (which `crossplane.parse()` returns) using string keys where integer indices are expected, or vice-versa, often due to misinterpreting the structure of the parsed NGINX configuration JSON.

fix

Carefully review the structure of the JSON output returned by `crossplane.parse()`. Ensure you are using correct dictionary keys (strings) to access directive properties and list indices (integers) for arrays of directives or blocks. For example, `config['config'][0]['parsed']` for the top-level parsed array, and then iterating or accessing elements within it by index for lists or by key for dictionaries.

crossplane: error: [Errno 2] No such file or directory

The `crossplane` CLI or `parse()` function was invoked with a file path that does not exist on the file system.

fix

Verify that the NGINX configuration file specified exists at the given path. Provide the correct absolute or relative path to the file.

unexpected "}" (or similar syntax error in parse output)

The `crossplane.parse()` function encountered an invalid NGINX configuration syntax (e.g., a missing semicolon, an unmatched brace, or an unknown directive) in the input file.

fix

Examine the NGINX configuration file, specifically around the indicated line number (if provided in `crossplane`'s error output), to identify and correct the syntax error. `crossplane` provides detailed error messages within the `errors` array of its JSON output, including the specific error and line number.

Upgrade

Version history

0.5.8latest on PyPI · released Sep 22, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nginxinc/crossplane ↗

packagehttps://pypi.org/project/crossplane/ ↗