{"id":28600670,"url":"https://github.com/xian-network/xian-linter","last_synced_at":"2026-05-15T22:05:25.837Z","repository":{"id":269889886,"uuid":"908387434","full_name":"xian-network/xian-linter","owner":"xian-network","description":"A FastAPI service that provides Python code linting specifically designed for Xian smart contracts","archived":false,"fork":false,"pushed_at":"2025-01-16T01:07:31.000Z","size":47,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-11T14:44:07.183Z","etag":null,"topics":["contracting","fastapi","linting","python","xian"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xian-network.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-26T00:16:55.000Z","updated_at":"2025-01-16T01:07:32.000Z","dependencies_parsed_at":"2024-12-27T00:19:52.456Z","dependency_job_id":"8f1ccc46-becc-4623-b3d7-4abf99ba7936","html_url":"https://github.com/xian-network/xian-linter","commit_stats":null,"previous_names":["endogen/xian-linter","xian-network/xian-linter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/xian-network/xian-linter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xian-network%2Fxian-linter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xian-network%2Fxian-linter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xian-network%2Fxian-linter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xian-network%2Fxian-linter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xian-network","download_url":"https://codeload.github.com/xian-network/xian-linter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xian-network%2Fxian-linter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278887262,"owners_count":26063154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["contracting","fastapi","linting","python","xian"],"created_at":"2025-06-11T14:30:46.792Z","updated_at":"2026-05-15T22:05:25.830Z","avatar_url":"https://github.com/xian-network.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xian Contract Linter\n\n[![PyPI version](https://badge.fury.io/py/xian-linter.svg)](https://badge.fury.io/py/xian-linter)\n[![Python versions](https://img.shields.io/pypi/pyversions/xian-linter.svg)](https://pypi.org/project/xian-linter/)\n\nA Python code linter specifically designed for Xian smart contracts. It combines PyFlakes for general Python linting with a custom Contracting linter to ensure contract code follows specific rules and patterns.\n\nThe linter can be used in two ways:\n- **Inline/Programmatic**: Import and use directly in your Python code without any server dependencies\n- **Standalone Server**: Run as a FastAPI service with HTTP endpoints for remote linting\n\n## Features\n\n- Parallel execution of linters (PyFlakes + Contracting)\n- Deduplication of error messages\n- Configurable whitelist patterns for ignored errors\n- Standardized error reporting format\n- Base64 and Gzip encoded code input support (server mode)\n- Input validation and size limits (server mode)\n\n## Installation\n\n### For Inline/Programmatic Usage\n\nInstall the base package without server dependencies:\n\n```bash\npip install xian-linter\n```\n\n### For Standalone Server Mode\n\nInstall with the server extras to include FastAPI and uvicorn:\n\n```bash\npip install xian-linter[server]\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/xian-network/xian-linter.git\ncd xian-linter\n\n# Install base dependencies using Poetry\npoetry install\n\n# Or install with server extras\npoetry install --extras server\n```\n\n## Usage\n\n### Inline/Programmatic Usage\n\nUse the linter directly in your Python code without running a server:\n\n```python\nfrom xian_linter import lint_code_inline\n\n# Your contract code as a string\ncontract_code = \"\"\"\ndef transfer():\n    sender_balance = balances[ctx.caller]\n    balances[ctx.caller] -= amount\n\"\"\"\n\n# Lint the code\nerrors = lint_code_inline(contract_code)\n\n# Check results\nif errors:\n    for error in errors:\n        print(f\"Line {error.position.line}: {error.message}\")\nelse:\n    print(\"No errors found!\")\n```\n\nYou can also provide custom whitelist patterns:\n\n```python\nerrors = lint_code_inline(\n    contract_code,\n    whitelist_patterns=['custom_pattern', 'another_pattern']\n)\n```\n\n### Standalone Server Mode\n\nRun the linter as a FastAPI service (requires `[server]` extras):\n\n#### Using the command-line script:\n```bash\nxian-linter\n```\n\n#### Using Python's module syntax:\n```bash\npython -m xian_linter\n```\n\n#### Using uvicorn directly:\n```bash\nuvicorn xian_linter.server:app --host 0.0.0.0 --port 8000\n```\n\n#### From source using Poetry:\n```bash\npoetry run xian-linter\n```\n\nThe server will start on `http://localhost:8000` by default.\n\n### API Endpoints\n\n#### POST /lint_base64\nExpects base64-encoded Python code in the request body.\n\n```bash\n# Example using curl\nbase64 \u003c contract.py \u003e contract.py.b64\ncurl -X POST \"http://localhost:8000/lint_base64\" --data-binary \"@contract.py.b64\"\n```\n\n#### POST /lint_gzip\nExpects gzipped Python code in the request body.\n\n```bash\n# Example using curl\ngzip -c contract.py \u003e contract.py.gz\ncurl -X POST \"http://localhost:8000/lint_gzip\" -H \"Content-Type: application/gzip\" --data-binary \"@contract.py.gz\"\n```\n\n### Query Parameters\n\n- `whitelist_patterns`: Comma-separated list of patterns to ignore in lint errors. Default patterns are provided for common Contracting keywords.\n\n### Response Format\n\n```json\n{\n    \"success\": false,\n    \"errors\": [\n        {\n            \"message\": \"Error description\",\n            \"severity\": \"error\",\n            \"position\": {\n                \"line\": 3,\n                \"column\": 1\n            }\n        }\n    ]\n}\n```\n\nThe `position` field is optional and may not be present for global errors.\n\n## Default Whitelist Patterns\n\nThe following patterns are ignored by default in Pyflakes checks:\n- `export`, `construct`\n- `Hash`, `Variable`, `ForeignHash`, `ForeignVariable`\n- `ctx`, `now`, `block_num`, `block_hash`, `chain_id`\n- `random`, `importlib`, `hashlib`, `datetime`, `crypto`, `decimal`\n- `Any`, `LogEvent`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxian-network%2Fxian-linter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxian-network%2Fxian-linter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxian-network%2Fxian-linter/lists"}