| Name | fx-bin JSON |
| Version |
1.3.4
JSON |
| download |
| home_page | None |
| Summary | A common bin collection for my own usage |
| upload_time | 2025-08-30 15:06:13 |
| maintainer | None |
| docs_url | None |
| author | Frank Xu |
| requires_python | <4.0,>=3.11 |
| license | None |
| keywords |
fx_bin
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
=======
FX Bin
=======
.. image:: https://img.shields.io/pypi/v/fx-bin.svg
:target: https://pypi.org/project/fx-bin/
:alt: PyPI Version
.. image:: https://img.shields.io/pypi/pyversions/fx-bin.svg
:target: https://pypi.org/project/fx-bin/
:alt: Python Versions
.. image:: https://img.shields.io/github/license/fx/fx_bin.svg
:target: https://github.com/fx/fx_bin/blob/main/LICENSE
:alt: License
A comprehensive Python utility collection providing command-line tools for file operations, directory analysis, text manipulation, and more. Built with security and safety as top priorities.
**Key Features:**
* 🔒 Security-first design with extensive safety checks
* ⚡ Fast and efficient file operations
* 🛡️ Atomic file operations to prevent data loss
* 📊 Comprehensive file and directory analysis
* 🔍 Advanced file search capabilities
* 🎯 **NEW**: Unified CLI with single ``fx`` command
* 🚀 Production-ready with extensive test coverage
Installation
============
Using pip (recommended)
------------------------
.. code-block:: bash
pip install --upgrade fx-bin
Using Poetry
------------
.. code-block:: bash
poetry add fx-bin
From source
-----------
.. code-block:: bash
git clone https://github.com/fx/fx_bin.git
cd fx_bin
pip install -e .
Quick Start
===========
FX Bin provides a unified ``fx`` command with subcommands for all utilities:
.. code-block:: bash
# List all available commands
fx list
# Get help for any command
fx --help
fx COMMAND --help
Available fx Commands
---------------------
.. code-block:: text
fx files - Count files in directories
fx size - Analyze file/directory sizes
fx ff - Find files by keyword
fx filter - Filter files by extension and sort by time
fx replace - Replace text in files
fx json2excel - Convert JSON to Excel
fx list - List all available commands
Examples
--------
.. code-block:: bash
# Count files in current directory
fx files
# Analyze directory sizes
fx size /path/to/directory
# Find Python files
fx ff "*.py"
# Replace text in files
fx replace "old_text" "new_text" file.txt
# Convert JSON to Excel
fx json2excel data.json output.xlsx
Available Commands
==================
fx size - Directory Size Analyzer
----------------------------------
Analyze and display file and directory sizes in human-readable format.
.. code-block:: bash
fx size # Current directory
fx size /path/to/dir # Specific directory
**Features:**
* Human-readable size formatting (B, KB, MB, GB)
* Sort by size automatically
* Handle symbolic links safely
* Recursive directory traversal with loop detection
fx files - File Counter
------------------------
Count files in directories with detailed statistics.
.. code-block:: bash
fx files # Current directory
fx files /path/to/dir # Specific directory
**Features:**
* Fast file counting
* Extension-based grouping
* Hidden files detection
* Recursive counting with depth control
fx ff - Find Files
------------------
Advanced file search utility with pattern matching.
.. code-block:: bash
fx ff "*.py" # Find Python files
fx ff config # Find files with 'config' in name
**Features:**
* Glob pattern matching
* Content search
* Size filtering
* Date filtering
* Regular expression support
fx filter - File Filter by Extension
-------------------------------------
Filter files by extension and sort by creation or modification time.
.. code-block:: bash
fx filter mp4 # Find all .mp4 files
fx filter "mp4,avi,mkv" # Multiple extensions
fx filter mp4 --sort-by modified # Sort by modification time
fx filter mp4 --no-recursive # Current directory only
fx filter mp4 --reverse # Oldest first
fx filter mp4 --format detailed # Show size and timestamps
**Features:**
* Filter by single or multiple extensions
* Sort by creation time (default) or modification time
* Recursive or non-recursive search
* Simple, detailed, or count-only output formats
* Reverse sorting option
fx replace - Text Replacement
------------------------------
Safe text replacement in files with atomic operations.
.. code-block:: bash
fx replace "old" "new" file.txt # Single file
fx replace "old" "new" *.txt # Multiple files
**Features:**
* Atomic file operations (no data loss)
* UTF-8 encoding support
* Permission preservation
* Backup creation
* Dry-run mode for preview
fx json2excel - JSON to Excel Converter
-----------------------------------------
Convert JSON API responses to Excel spreadsheets.
.. code-block:: bash
fx json2excel data.json output.xlsx # Convert JSON file
fx json2excel https://api.example.com/data output.xlsx # From API
**Note:** Requires pandas installation: ``pip install fx-bin[excel]``
Security & Safety
=================
FX Bin prioritizes security and safety in all operations:
**Security Features:**
* ✅ **Path Traversal Protection**: Prevents directory traversal attacks
* ✅ **Input Sanitization**: All user inputs are validated and sanitized
* ✅ **Safe File Operations**: Atomic operations prevent data corruption
* ✅ **Resource Limits**: Memory and CPU usage constraints
* ✅ **Symlink Loop Detection**: Prevents infinite loops in directory traversal
**Safety Guarantees:**
* No file descriptor leaks
* Graceful error handling
* Original file permissions preserved
* Automatic backup options
* Dry-run mode for preview
Development
===========
Setting up development environment
-----------------------------------
.. code-block:: bash
# Clone the repository
git clone https://github.com/fx/fx_bin.git
cd fx_bin
# Install with Poetry (recommended)
poetry install --with dev
# Or using pip
pip install -e .
pip install -r requirements_dev.txt
Running tests
-------------
.. code-block:: bash
# Run all tests with pytest
poetry run pytest
# Run specific test modules
poetry run pytest tests/test_cli.py -v
poetry run pytest tests/test_size.py -v
# Run with coverage
poetry run pytest --cov=fx_bin --cov-report=html
# Run security tests only
poetry run pytest tests/test_*security*.py -v --no-cov
Test Coverage
-------------
The project maintains comprehensive test coverage:
* Security vulnerability tests
* File operation safety tests
* Performance benchmarks
* Integration tests
* Unit tests for all modules
* CLI command tests (new in v0.10.0)
Code Quality
------------
.. code-block:: bash
# Run linting
poetry run flake8 fx_bin/
# Run type checking
poetry run mypy fx_bin/
# Format code
poetry run black fx_bin/ tests/
Architecture
============
Project Structure
-----------------
.. code-block:: text
fx_bin/
├── fx_bin/ # Main package
│ ├── cli.py # NEW: Unified CLI entry point
│ ├── common.py # Shared utilities
│ ├── size.py # Size analyzer implementation
│ ├── files.py # File counter implementation
│ ├── find_files.py # File finder implementation
│ ├── replace.py # Text replacement implementation
│ └── pd.py # JSON to Excel converter
├── tests/ # Test suite
│ ├── test_cli.py # NEW: CLI tests
│ ├── runners/ # Test execution scripts
│ └── test_*.py # Test modules
└── docs/ # Documentation
└── testing/ # Testing guides
Design Principles
-----------------
1. **Security First**: All operations validated for security
2. **Fail Safe**: Graceful error handling and recovery
3. **Atomic Operations**: Prevent partial updates
4. **Resource Efficient**: Memory and CPU constraints
5. **Cross-Platform**: Works on Linux, macOS, Windows
6. **User-Friendly**: Unified CLI for better usability (new in v0.10.0)
Requirements
============
* Python 3.11 or higher
* click (CLI framework)
* loguru (logging)
* psutil (system operations)
* pandas (optional, for Excel features)
Command Reference
=================
All commands are accessed through the unified ``fx`` CLI:
.. code-block:: bash
fx files # Count files
fx size # Analyze sizes
fx ff "*.py" # Find files
fx replace "old" "new" file # Replace text
fx json2excel data.json out # Convert JSON to Excel
fx list # List all commands
The new CLI provides:
* Single entry point (``fx``)
* Consistent command structure
* Built-in command listing (``fx list``)
* Better help system (``fx --help``, ``fx COMMAND --help``)
Contributing
============
Contributions are welcome! Please follow these steps:
1. Fork the repository
2. Create a feature branch (``git checkout -b feature/amazing-feature``)
3. Make your changes
4. Run tests to ensure everything works
5. Commit your changes (``git commit -m 'Add amazing feature'``)
6. Push to your branch (``git push origin feature/amazing-feature``)
7. Open a Pull Request
Please ensure:
* All tests pass
* Code follows project style (use ``black`` for formatting)
* Security tests pass for any file operation changes
* Documentation is updated for new features
License
=======
This project is licensed under the MIT License - see the LICENSE file for details.
Support
=======
* **Issues**: https://github.com/fx/fx_bin/issues
* **Discussions**: https://github.com/fx/fx_bin/discussions
* **PyPI**: https://pypi.org/project/fx-bin/
Acknowledgments
===============
Built with:
* `Click <https://click.palletsprojects.com/>`_ for CLI interfaces
* `Loguru <https://github.com/Delgan/loguru>`_ for logging
* `psutil <https://github.com/giampaolo/psutil>`_ for system operations
Security testing powered by:
* `Bandit <https://github.com/PyCQA/bandit>`_ for security analysis
* `Safety <https://github.com/pyupio/safety>`_ for dependency scanning
---
**Made with ❤️ for the Python community**
Raw data
{
"_id": null,
"home_page": null,
"name": "fx-bin",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "fx_bin",
"author": "Frank Xu",
"author_email": "frank@frankxu.me",
"download_url": "https://files.pythonhosted.org/packages/e9/9a/3b8bfbb7d000a87cea0ea63b9e41f00171fda47e83a928f9a31f39bd690e/fx_bin-1.3.4.tar.gz",
"platform": null,
"description": "=======\nFX Bin\n=======\n\n.. image:: https://img.shields.io/pypi/v/fx-bin.svg\n :target: https://pypi.org/project/fx-bin/\n :alt: PyPI Version\n\n.. image:: https://img.shields.io/pypi/pyversions/fx-bin.svg\n :target: https://pypi.org/project/fx-bin/\n :alt: Python Versions\n\n.. image:: https://img.shields.io/github/license/fx/fx_bin.svg\n :target: https://github.com/fx/fx_bin/blob/main/LICENSE\n :alt: License\n\nA comprehensive Python utility collection providing command-line tools for file operations, directory analysis, text manipulation, and more. Built with security and safety as top priorities.\n\n**Key Features:**\n\n* \ud83d\udd12 Security-first design with extensive safety checks\n* \u26a1 Fast and efficient file operations\n* \ud83d\udee1\ufe0f Atomic file operations to prevent data loss\n* \ud83d\udcca Comprehensive file and directory analysis\n* \ud83d\udd0d Advanced file search capabilities\n* \ud83c\udfaf **NEW**: Unified CLI with single ``fx`` command\n* \ud83d\ude80 Production-ready with extensive test coverage\n\nInstallation\n============\n\nUsing pip (recommended)\n------------------------\n\n.. code-block:: bash\n\n pip install --upgrade fx-bin\n\nUsing Poetry\n------------\n\n.. code-block:: bash\n\n poetry add fx-bin\n\nFrom source\n-----------\n\n.. code-block:: bash\n\n git clone https://github.com/fx/fx_bin.git\n cd fx_bin\n pip install -e .\n\nQuick Start\n===========\n\nFX Bin provides a unified ``fx`` command with subcommands for all utilities:\n\n.. code-block:: bash\n\n # List all available commands\n fx list\n \n # Get help for any command\n fx --help\n fx COMMAND --help\n\nAvailable fx Commands\n---------------------\n\n.. code-block:: text\n\n fx files - Count files in directories\n fx size - Analyze file/directory sizes\n fx ff - Find files by keyword\n fx filter - Filter files by extension and sort by time\n fx replace - Replace text in files\n fx json2excel - Convert JSON to Excel\n fx list - List all available commands\n\nExamples\n--------\n\n.. code-block:: bash\n\n # Count files in current directory\n fx files\n \n # Analyze directory sizes\n fx size /path/to/directory\n \n # Find Python files\n fx ff \"*.py\"\n \n # Replace text in files\n fx replace \"old_text\" \"new_text\" file.txt\n \n # Convert JSON to Excel\n fx json2excel data.json output.xlsx\n\nAvailable Commands\n==================\n\nfx size - Directory Size Analyzer\n----------------------------------\n\nAnalyze and display file and directory sizes in human-readable format.\n\n.. code-block:: bash\n\n fx size # Current directory\n fx size /path/to/dir # Specific directory\n\n**Features:**\n\n* Human-readable size formatting (B, KB, MB, GB)\n* Sort by size automatically\n* Handle symbolic links safely\n* Recursive directory traversal with loop detection\n\nfx files - File Counter\n------------------------\n\nCount files in directories with detailed statistics.\n\n.. code-block:: bash\n\n fx files # Current directory\n fx files /path/to/dir # Specific directory\n\n**Features:**\n\n* Fast file counting\n* Extension-based grouping\n* Hidden files detection\n* Recursive counting with depth control\n\nfx ff - Find Files\n------------------\n\nAdvanced file search utility with pattern matching.\n\n.. code-block:: bash\n\n fx ff \"*.py\" # Find Python files\n fx ff config # Find files with 'config' in name\n\n**Features:**\n\n* Glob pattern matching\n* Content search\n* Size filtering\n* Date filtering\n* Regular expression support\n\nfx filter - File Filter by Extension\n-------------------------------------\n\nFilter files by extension and sort by creation or modification time.\n\n.. code-block:: bash\n\n fx filter mp4 # Find all .mp4 files\n fx filter \"mp4,avi,mkv\" # Multiple extensions\n fx filter mp4 --sort-by modified # Sort by modification time\n fx filter mp4 --no-recursive # Current directory only\n fx filter mp4 --reverse # Oldest first\n fx filter mp4 --format detailed # Show size and timestamps\n\n**Features:**\n\n* Filter by single or multiple extensions\n* Sort by creation time (default) or modification time\n* Recursive or non-recursive search\n* Simple, detailed, or count-only output formats\n* Reverse sorting option\n\nfx replace - Text Replacement\n------------------------------\n\nSafe text replacement in files with atomic operations.\n\n.. code-block:: bash\n\n fx replace \"old\" \"new\" file.txt # Single file\n fx replace \"old\" \"new\" *.txt # Multiple files\n\n**Features:**\n\n* Atomic file operations (no data loss)\n* UTF-8 encoding support\n* Permission preservation\n* Backup creation\n* Dry-run mode for preview\n\nfx json2excel - JSON to Excel Converter\n-----------------------------------------\n\nConvert JSON API responses to Excel spreadsheets.\n\n.. code-block:: bash\n\n fx json2excel data.json output.xlsx # Convert JSON file\n fx json2excel https://api.example.com/data output.xlsx # From API\n\n**Note:** Requires pandas installation: ``pip install fx-bin[excel]``\n\nSecurity & Safety\n=================\n\nFX Bin prioritizes security and safety in all operations:\n\n**Security Features:**\n\n* \u2705 **Path Traversal Protection**: Prevents directory traversal attacks\n* \u2705 **Input Sanitization**: All user inputs are validated and sanitized\n* \u2705 **Safe File Operations**: Atomic operations prevent data corruption\n* \u2705 **Resource Limits**: Memory and CPU usage constraints\n* \u2705 **Symlink Loop Detection**: Prevents infinite loops in directory traversal\n\n**Safety Guarantees:**\n\n* No file descriptor leaks\n* Graceful error handling\n* Original file permissions preserved\n* Automatic backup options\n* Dry-run mode for preview\n\nDevelopment\n===========\n\nSetting up development environment\n-----------------------------------\n\n.. code-block:: bash\n\n # Clone the repository\n git clone https://github.com/fx/fx_bin.git\n cd fx_bin\n \n # Install with Poetry (recommended)\n poetry install --with dev\n \n # Or using pip\n pip install -e .\n pip install -r requirements_dev.txt\n\nRunning tests\n-------------\n\n.. code-block:: bash\n\n # Run all tests with pytest\n poetry run pytest\n \n # Run specific test modules\n poetry run pytest tests/test_cli.py -v\n poetry run pytest tests/test_size.py -v\n \n # Run with coverage\n poetry run pytest --cov=fx_bin --cov-report=html\n \n # Run security tests only\n poetry run pytest tests/test_*security*.py -v --no-cov\n\nTest Coverage\n-------------\n\nThe project maintains comprehensive test coverage:\n\n* Security vulnerability tests\n* File operation safety tests\n* Performance benchmarks\n* Integration tests\n* Unit tests for all modules\n* CLI command tests (new in v0.10.0)\n\nCode Quality\n------------\n\n.. code-block:: bash\n\n # Run linting\n poetry run flake8 fx_bin/\n \n # Run type checking\n poetry run mypy fx_bin/\n \n # Format code\n poetry run black fx_bin/ tests/\n\nArchitecture\n============\n\nProject Structure\n-----------------\n\n.. code-block:: text\n\n fx_bin/\n \u251c\u2500\u2500 fx_bin/ # Main package\n \u2502 \u251c\u2500\u2500 cli.py # NEW: Unified CLI entry point\n \u2502 \u251c\u2500\u2500 common.py # Shared utilities\n \u2502 \u251c\u2500\u2500 size.py # Size analyzer implementation\n \u2502 \u251c\u2500\u2500 files.py # File counter implementation\n \u2502 \u251c\u2500\u2500 find_files.py # File finder implementation\n \u2502 \u251c\u2500\u2500 replace.py # Text replacement implementation\n \u2502 \u2514\u2500\u2500 pd.py # JSON to Excel converter\n \u251c\u2500\u2500 tests/ # Test suite\n \u2502 \u251c\u2500\u2500 test_cli.py # NEW: CLI tests\n \u2502 \u251c\u2500\u2500 runners/ # Test execution scripts\n \u2502 \u2514\u2500\u2500 test_*.py # Test modules\n \u2514\u2500\u2500 docs/ # Documentation\n \u2514\u2500\u2500 testing/ # Testing guides\n\nDesign Principles\n-----------------\n\n1. **Security First**: All operations validated for security\n2. **Fail Safe**: Graceful error handling and recovery\n3. **Atomic Operations**: Prevent partial updates\n4. **Resource Efficient**: Memory and CPU constraints\n5. **Cross-Platform**: Works on Linux, macOS, Windows\n6. **User-Friendly**: Unified CLI for better usability (new in v0.10.0)\n\nRequirements\n============\n\n* Python 3.11 or higher\n* click (CLI framework)\n* loguru (logging)\n* psutil (system operations)\n* pandas (optional, for Excel features)\n\nCommand Reference\n=================\n\nAll commands are accessed through the unified ``fx`` CLI:\n\n.. code-block:: bash\n\n fx files # Count files\n fx size # Analyze sizes\n fx ff \"*.py\" # Find files\n fx replace \"old\" \"new\" file # Replace text\n fx json2excel data.json out # Convert JSON to Excel\n fx list # List all commands\n\nThe new CLI provides:\n\n* Single entry point (``fx``)\n* Consistent command structure\n* Built-in command listing (``fx list``)\n* Better help system (``fx --help``, ``fx COMMAND --help``)\n\nContributing\n============\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (``git checkout -b feature/amazing-feature``)\n3. Make your changes\n4. Run tests to ensure everything works\n5. Commit your changes (``git commit -m 'Add amazing feature'``)\n6. Push to your branch (``git push origin feature/amazing-feature``)\n7. Open a Pull Request\n\nPlease ensure:\n\n* All tests pass\n* Code follows project style (use ``black`` for formatting)\n* Security tests pass for any file operation changes\n* Documentation is updated for new features\n\nLicense\n=======\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\nSupport\n=======\n\n* **Issues**: https://github.com/fx/fx_bin/issues\n* **Discussions**: https://github.com/fx/fx_bin/discussions\n* **PyPI**: https://pypi.org/project/fx-bin/\n\nAcknowledgments\n===============\n\nBuilt with:\n\n* `Click <https://click.palletsprojects.com/>`_ for CLI interfaces\n* `Loguru <https://github.com/Delgan/loguru>`_ for logging\n* `psutil <https://github.com/giampaolo/psutil>`_ for system operations\n\nSecurity testing powered by:\n\n* `Bandit <https://github.com/PyCQA/bandit>`_ for security analysis\n* `Safety <https://github.com/pyupio/safety>`_ for dependency scanning\n\n---\n\n**Made with \u2764\ufe0f for the Python community**\n",
"bugtrack_url": null,
"license": null,
"summary": "A common bin collection for my own usage",
"version": "1.3.4",
"project_urls": {
"Repository": "https://github.com/frankyxhl/fx_bin"
},
"split_keywords": [
"fx_bin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "14999f17eb35fe5edea580ee51b278660bdcad99e68469d1f1fb7276acdabbd3",
"md5": "8258c7c2d399671a60c31cacd9e62fe9",
"sha256": "4275e15f9d3f170f52320e13ef4f5b2dd7beec6d40010bd88edebd43f03eb95e"
},
"downloads": -1,
"filename": "fx_bin-1.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8258c7c2d399671a60c31cacd9e62fe9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 26653,
"upload_time": "2025-08-30T15:06:12",
"upload_time_iso_8601": "2025-08-30T15:06:12.550383Z",
"url": "https://files.pythonhosted.org/packages/14/99/9f17eb35fe5edea580ee51b278660bdcad99e68469d1f1fb7276acdabbd3/fx_bin-1.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e99a3b8bfbb7d000a87cea0ea63b9e41f00171fda47e83a928f9a31f39bd690e",
"md5": "6fa7bad872fa693eccbf133f71b2befd",
"sha256": "99d4d58318b027bd5472d6055f54ad6deeafe69fe82ad5bb34a058d40a8bb030"
},
"downloads": -1,
"filename": "fx_bin-1.3.4.tar.gz",
"has_sig": false,
"md5_digest": "6fa7bad872fa693eccbf133f71b2befd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 23743,
"upload_time": "2025-08-30T15:06:13",
"upload_time_iso_8601": "2025-08-30T15:06:13.778907Z",
"url": "https://files.pythonhosted.org/packages/e9/9a/3b8bfbb7d000a87cea0ea63b9e41f00171fda47e83a928f9a31f39bd690e/fx_bin-1.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 15:06:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "frankyxhl",
"github_project": "fx_bin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "fx-bin"
}
