{"id":48020697,"url":"https://github.com/cadentdev/xplat","last_synced_at":"2026-04-04T13:46:51.090Z","repository":{"id":38885124,"uuid":"466862909","full_name":"cadentdev/xplat","owner":"cadentdev","description":"Cross-platform Python tools for file management and conversion","archived":false,"fork":false,"pushed_at":"2026-02-23T00:46:40.000Z","size":2958,"stargazers_count":1,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-23T04:29:06.349Z","etag":null,"topics":["conversion","filesystem","linux","macos","python","windows"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cadentdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-03-06T21:38:15.000Z","updated_at":"2026-02-23T00:45:44.000Z","dependencies_parsed_at":"2025-09-08T06:12:07.878Z","dependency_job_id":"0a615055-20e4-4668-833f-16ee5402ecca","html_url":"https://github.com/cadentdev/xplat","commit_stats":null,"previous_names":["cadentdev/xplat"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cadentdev/xplat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cadentdev%2Fxplat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cadentdev%2Fxplat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cadentdev%2Fxplat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cadentdev%2Fxplat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cadentdev","download_url":"https://codeload.github.com/cadentdev/xplat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cadentdev%2Fxplat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31402276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["conversion","filesystem","linux","macos","python","windows"],"created_at":"2026-04-04T13:46:50.902Z","updated_at":"2026-04-04T13:46:51.065Z","avatar_url":"https://github.com/cadentdev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xplat\n\n[![Coverage Status](https://coveralls.io/repos/github/cadentdev/xplat/badge.svg?branch=main)](https://coveralls.io/github/cadentdev/xplat?branch=main)\n\n(Coverage stats for the main branch)\n\n## Cross-platform Python tools for batch file management and conversion at the command line\n\nIf you have to work with lots of files on different computing platforms, `xplat` is here to help. Uploading files from your notebook to a web server? Use `xplat rename` to change the file names so they won't break your web browser. Want to know more about your computer or Python installation? Use `xplat info` for a detailed system report.\n\nCreated for Python 3.12 or later, this package uses the [pathlib module, Object-oriented filesystem paths](https://docs.python.org/3/library/pathlib.html), introduced in Python 3.4, to work with files on all platforms.\n\n## xplat Features\n\nDesigned from the start to work across platforms, `xplat` includes these features:\n\n- Extensive command-line help.\n- Tested on Mac, Linux, and Windows.\n- Works with individual files or directories.\n\n## Getting Started\n\n1. Create a fork of this repo on your computer.\n2. Install Poetry if you haven't already:\n   - Visit https://python-poetry.org/docs/#installation\n   - Or use: `curl -sSL https://install.python-poetry.org | python3 -`\n   - Verify with: `poetry --version`\n3. In the root directory of this project, run `poetry install` to ensure you have all the required packages\n4. Start the virtual environment: `poetry shell`\n5. Run `xplat --help` for a list of subcommands and options.\n6. (Optional) Run `xplat --install-completion` with the name of your shell (bash, zsh, fish, etc.) to enable tab completion.\n\nNote: if you don't want to invoke the poetry virtual environment using `poetry shell`, you can simply prefix your commands with `poetry run`. For example, enter `poetry run xplat --help`.\n\n## Installing with pipx\n\nIf you just want to use `xplat` as a standalone command without activating a virtual environment, [pipx](https://pipx.pypa.io/) is the recommended approach. It installs Python CLI tools into isolated environments and makes them available globally.\n\n### Install pipx\n\nIf you don't already have pipx:\n\n```bash\n# macOS\nbrew install pipx\npipx ensurepath\n\n# Linux / Windows\npip install --user pipx\npipx ensurepath\n```\n\nRestart your shell after running `ensurepath` so the PATH changes take effect.\n\n### Standard install\n\n```bash\npipx install /path/to/xplat\n```\n\nThis creates an isolated virtualenv for xplat and adds the `xplat` command to your PATH. Use this when you want a stable, fixed version.\n\n### Editable install (recommended for development)\n\n```bash\npipx install --editable /path/to/xplat\n```\n\nWith an editable install, changes you make to the source code are reflected immediately — no reinstall needed. This is ideal if you're actively working on xplat.\n\n### Verify the installation\n\n```bash\nxplat --help\n```\n\n### Uninstall\n\n```bash\npipx uninstall xplat\n```\n\n## Development and Testing\n\n### Running Tests\n\nIf the steps described above in the **Getting Started** section worked for you, you'll also be able to run the `pytest` test suite:\n\n```bash\npytest\n```\n\nTo see a code coverage report:\n\n```bash\npytest --cov-report term-missing --cov=src/\n```\n\n### Code Quality\n\nThis project uses modern Python tooling for code quality:\n\n```bash\n# Lint and format code (replaces flake8 + isort)\npoetry run ruff check .\npoetry run ruff format .\n\n# Auto-fix many linting issues\npoetry run ruff check . --fix\n\n# Type checking\npoetry run mypy .\n\n# Security scanning\npoetry run bandit -r src/\npoetry run pip-audit\n\n# Comprehensive quality check\npoetry run pytest \u0026\u0026 poetry run ruff check . \u0026\u0026 poetry run mypy . --no-error-summary\n```\n\n**Current Quality Status** (2026-02-22):\n- Tests: 74/74 passing (100%)\n- Coverage: 98%\n- MyPy: 0 errors across 6 source files\n- Ruff: 0 linting or formatting issues\n- Bandit: 0 security findings\n- pip-audit: 0 known vulnerabilities\n- CI: Green on Ubuntu, macOS, Windows (Python 3.12, 3.13)\n\n### Pre-commit Hooks (Recommended)\n\nSet up automated code quality checks before each commit:\n\n```bash\n# Install pre-commit hooks\npoetry run pre-commit install\n\n# Run all checks manually\npoetry run pre-commit run --all-files\n```\n\nOnce installed, the hooks will automatically run ruff, mypy, bandit, and other quality checks before each commit.\n\n**Development Workflow**:\n1. Install dependencies: `poetry install`\n2. Set up pre-commit: `poetry run pre-commit install`\n3. Develop with automatic quality checks on commit\n4. Before pushing: `poetry run pytest \u0026\u0026 poetry run ruff check . \u0026\u0026 poetry run mypy . --no-error-summary`\n\n### Reporting Issues\n\nIf you find an error, please report it by creating an issue on this repo.\n\n## Subcommands\n\nThe `xplat` utility offers several useful sub-commands (or, more simply, _commands_). Here's the current list, from `xplat --help`\n\n```bash\nCommands:\n  info    Display platform information.\n  list    List files in a directory, or info for a file.\n  rename  Convert file names for cross-platform compatibility.\n```\n\n### info\n\nDisplay platform information, from Python's perspective. Useful for troubleshooting and debugging. Here's the sample output from a Mac M1 mini:\n\n```bash\n➤ xplat info\n\n-- Platform Information --------------------\nmacOS-12.4-arm64-arm-64bit\n\n-- System Information ----------------------\nSystem:          Darwin\nNode:            My-Mac-mini.local\nRelease:         21.5.0\nVersion:         Darwin Kernel Version 21.5.0: Tue Apr 26 21:08:29 PDT 2022; root:xnu-8020.121.3~4/RELEASE_ARM64_T8101\nMachine:         arm64\n\n-- Python Information ----------------------\nPython Branch:                 (not found)\nPython Compiler:               Clang 13.1.6 (clang-1316.0.21.2)\nPython Implementation:         CPython\nPython Revision:               (not found)\nPython Version:                3.9.13\n\n-- macOS Information -----------------------\nmacOS Version:                 12.4\n```\n\n### list\n\nList files in the specified directory. Especially useful to see which files you'll modify with any of the other conversion commands, since it uses the same file listing code as the other commands.\n\nAlso lists file information for individual files. Either provide the path to the file, or select a file from the list.\n\nSome examples:\n\n```bash\n# list all the files (no directories) in your home directory\nxplat list ~\n\n# list all pdf files in ~/Downloads -- note the ext is case-sensitive\nxplat list ~/Downloads/ --ext pdf\n```\n\n## rename\n\nConvert file names for cross-platform and web compatibility using a style-based system. Four naming styles are available:\n\n| Style | Separator | Example |\n|-------|-----------|---------|\n| **web** (default) | hyphens | `My File.v2.txt` → `my-file-v2.txt` |\n| **snake** | underscores | `My File.v2.txt` → `my_file_v2.txt` |\n| **kebab** | hyphens (converts underscores too) | `My_File.v2.txt` → `my-file-v2.txt` |\n| **camel** | none | `My File.v2.txt` → `myFileV2.txt` |\n\nAll styles normalize Unicode whitespace, strip leading/trailing spaces, collapse consecutive separators, and lowercase extensions.\n\nThe source is a positional argument — pass a file, a directory, or omit it to use the current directory.\n\nOptions:\n\n- `--style`: Naming style — `web`, `snake`, `kebab`, or `camel` (default: `web`)\n- `-o, --output-dir`: Output directory to save renamed files\n- `-e, --ext`: Case-sensitive file extension filter\n- `-n, --dry-run`: Preview changes without modifying files\n- `-i, --interactive`: Prompt for confirmation before each rename\n\nSome examples:\n\n```bash\n# Preview name conversion for all files in ~/Downloads (web style, default)\nxplat rename ~/Downloads --dry-run\n\n# Rename using snake_case style\nxplat rename ~/Downloads --style snake --dry-run\n\n# Move and rename all PDF files from ~/Downloads to ~/temp\nxplat rename ~/Downloads --output-dir ~/temp --ext pdf\n\n# Rename a single file\nxplat rename ~/Photos/My\\ Photo.PNG\n\n# Rename files in current directory with interactive confirmation\nxplat rename --interactive\n\n# Preview renaming of JPG files only using kebab-case\nxplat rename ~/Photos --ext jpg --style kebab --dry-run\n```\n\n## macOS Integration\n\nAutomate xplat with a **launchd folder watcher** (auto-rename files dropped into a folder) or a **Finder Quick Action** (right-click to rename). See [MAC-INTEGRATION.md](MAC-INTEGRATION.md) for setup instructions.\n\n## FAQ\n\nSome questions and answers about the `xplat` utility.\n\n### Why doesn't xplat do X?\n\nI've added the different features as I've needed them for my web development work. If you'd like to suggest a new feature, add an issue on this repo.\n\n### I can already do this thing using another program on my favorite computer. Why would I want to use xplat?\n\nBecause:\n\n- You might want to perform the same types of conversions to a larger group of files, not just one, and xplat is designed to process many files at once.\n- You'd like to automate your workflow  using bash scripts.\n- You have to switch from one type of computer to another and the program you used to use for converting files is not available / crazy expensive / no fun to use on the new platform.\n- You want to contribute to open source.\n\n### I can't code, but I want to help! What can I do?\n\n- If you find a bug, let us know: please report it by creating an issue on this repo.\n- You can help improve the documentation, by writing, editing, or creating diagrams.\n- You can help translate the program to a different language.\n\n### Why is xplat so slow?\n\nBecause xplat is written as a cross-platform tool, not all of the code has been compiled and optimized for your specific platform. Having said that, if you're using `xplat` to process hundreds, or thousands, of files, let us know how you're using the program and perhaps we'll code up some optimizations or add multi-threaded execution to speed things up for you.\n\nIn general, though, `xplat` was designed to run through a set of files without intervention, after you've selected your options and answered a few prompts. You can just let it run in the background or overnight while you do something else.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcadentdev%2Fxplat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcadentdev%2Fxplat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcadentdev%2Fxplat/lists"}