{"id":2449,"library":"crossplane","title":"Crossplane NGINX Configuration Parser","description":"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.","status":"active","version":"0.5.8","language":"en","source_language":"en","source_url":"https://github.com/nginxinc/crossplane","tags":["nginx","parser","configuration","builder"],"install":[{"cmd":"pip install crossplane","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Used to parse an NGINX configuration file into a Python object/JSON structure.","symbol":"parse","correct":"from crossplane import parse"},{"note":"Used to build an NGINX configuration string from a parsed Python object/JSON structure.","symbol":"build","correct":"from crossplane import build"},{"note":"Used to tokenize an NGINX configuration file.","symbol":"lex","correct":"from crossplane import lex"}],"quickstart":{"code":"from crossplane import parse, build\nimport json\n\nnginx_config_content = '''\nuser  nginx;\nworker_processes  1;\n\nerror_log  /var/log/nginx/error.log warn;\npid        /var/run/nginx.pid;\n\nevents {\n    worker_connections  1024;\n}\n\nhttp {\n    include       /etc/nginx/mime.types;\n    default_type  application/octet-stream;\n\n    log_format  main  '$remote_addr - $remote_user [$time_local] \"$request\" '\n                      '$status $body_bytes_sent \"$http_referer\" '\n                      '\"$http_user_agent\" \"$http_x_forwarded_for\";\n\n    access_log  /var/log/nginx/access.log  main;\n\n    sendfile        on;\n    #tcp_nopush     on;\n\n    keepalive_timeout  65;\n\n    #gzip  on;\n\n    server {\n        listen       80;\n        server_name  localhost;\n\n        location / {\n            root   /usr/share/nginx/html;\n            index  index.html index.htm;\n        }\n\n        error_page   500 502 503 504  /50x.html;\n        location = /50x.html {\n            root   /usr/share/nginx/html;\n        }\n    }\n}\n'''\n\n# Parse the NGINX configuration string\nparsed_config = parse(nginx_config_content, filename='nginx.conf')\n\n# Print the parsed structure (JSON representation)\nprint(\"Parsed NGINX Config (JSON):\")\nprint(json.dumps(parsed_config, indent=2))\n\n# Example of accessing parsed data\nif parsed_config['status'] == 'ok' and parsed_config['config']:\n    first_file_config = parsed_config['config'][0]['parsed']\n    print(f\"\\nWorker processes: {first_file_config[1]['args'][0]}\")\n\n    # Build the config back into a string (simplified, without complex includes)\n    # For real file paths, ensure the 'filename' parameter matches where crossplane expects to find included files.\n    rebuilt_config = build(parsed_config)\n    print(\"\\nRebuilt NGINX Config:\")\n    print(rebuilt_config)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":"<0.5.2"},{"fix":"Upgrade to crossplane v0.5.8 or newer for robust handling of diverse character encodings in NGINX configurations.","message":"Parsing 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.","severity":"gotcha","affected_versions":"<0.5.8"},{"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.","message":"In 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.","severity":"gotcha","affected_versions":"<0.5.1"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}