fx-bin

Name	fx-bin JSON
Version	1.4.0 JSON
	download
home_page	None
Summary	A common bin collection for my own usage
upload_time	2025-09-07 00:17:10
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

[![PyPI version](https://badge.fury.io/py/fx-bin.svg)](https://badge.fury.io/py/fx-bin)
[![Python](https://img.shields.io/pypi/pyversions/fx-bin.svg)](https://pypi.org/project/fx-bin/)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/frankyxhl/fx_bin)
[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)](https://github.com/frankyxhl/fx_bin)
[![Security](https://img.shields.io/badge/security-A+-brightgreen.svg)](https://github.com/frankyxhl/fx_bin)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**A powerful, secure, and well-tested collection of Python file operation utilities with a unified CLI.**

## 📋 Table of Contents

- [Why fx-bin?](#-why-fx-bin)
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [Commands](#-commands)
- [Usage Examples](#-usage-examples)
- [Development](#-development)
- [Testing](#-testing)
- [Security](#-security)
- [Contributing](#-contributing)
- [License](#-license)

## 🤔 Why fx-bin?

**fx-bin** addresses common pain points in file operations:

- **Unified Interface**: One command (`fx`) for all file operations - no need to remember multiple tools
- **Safety First**: Built-in safeguards prevent accidental data loss (especially in `fx replace`)
- **Performance**: Optimized algorithms handle large directories and files efficiently
- **Cross-Platform**: Works seamlessly on Windows, macOS, and Linux
- **Developer Friendly**: Comprehensive testing (95%+ coverage) and clean, maintainable code
- **Security Focused**: Regular security audits, safe path handling, and input validation
- **Modern Python**: Built with Python 3.11+ features and best practices

Whether you're organizing files, analyzing disk usage, performing bulk text replacements, or filtering files by type, fx-bin provides a reliable, fast, and safe solution.

## ✨ Features

### Core Capabilities

- 📁 **File Counting** - Quickly count files in directories with pattern matching
- 📊 **Size Analysis** - Analyze file and directory sizes with human-readable output
- 🔍 **File Finding** - Search for files by keywords with multiple search strategies
- 🎯 **File Filtering** - Filter files by extension with intelligent sorting (NEW in v1.2.0!)
- 🔄 **Text Replacement** - Safe, bulk text replacement across files with backup options
- 📈 **JSON to Excel** - Convert JSON data to Excel spreadsheets
- 📋 **Command Listing** - Built-in help and command discovery

### Technical Excellence

- 🛡️ **Security Hardened** - Protection against path traversal, command injection, and other vulnerabilities
- ✅ **Thoroughly Tested** - TDD/BDD methodology with 95%+ test coverage
- 🚀 **High Performance** - Optimized for large-scale operations
- 🔧 **Extensible** - Clean architecture for easy feature additions
- 📝 **Well Documented** - Comprehensive documentation and examples

## 🚀 Quick Start

```bash
# Install fx-bin
pip install fx-bin  # or: pipx install fx-bin

# Show help and available commands
fx help              # Same as fx -h
fx list              # Show all available commands

# Count Python files
fx files . --pattern "*.py"

# Find large files
fx size . --limit 10 --unit MB

# Filter documents by extension
fx filter ~/Documents "pdf,docx" --format detailed

# Find files containing keyword
fx ff . "TODO"

# Safe text replacement
fx replace . "old_text" "new_text" --preview
```

## 📦 Installation

### Via pip (Recommended)

```bash
pip install fx-bin
```

### Via pipx (For Isolated Installation)

```bash
pipx install fx-bin
```

### From Source

```bash
git clone https://github.com/frankyxhl/fx_bin.git
cd fx_bin
poetry install
poetry run fx --help
```

### Requirements

- Python 3.11 or higher
- No external dependencies required for core functionality
- Optional: pandas for Excel operations (`pip install fx-bin[excel]`)

## 🛠️ Commands

### Overview

| Command | Description | Key Features |
|---------|-------------|--------------|
| `fx files` | Count files in directories | Pattern matching, recursive search, detailed stats |
| `fx size` | Analyze file/directory sizes | Human-readable units, sorting, limit results |
| `fx ff` | Find files by keyword | Multiple search modes, content search, regex support |
| `fx filter` | Filter files by extension | Time-based sorting, multiple formats, recursive search |
| `fx replace` | Replace text in files | Preview mode, backup creation, pattern exclusion |
| `fx json2excel` | Convert JSON to Excel | Automatic formatting, multiple sheets |
| `fx list` | List all available commands | Help and usage information |

### Detailed Command Documentation

#### 📁 fx files - File Counter

Count files in directories with powerful filtering options.

```bash
# Basic usage
fx files /path/to/directory

# Count only Python files
fx files . --pattern "*.py"

# Exclude test files
fx files . --exclude "*test*"

# Recursive search with details
fx files . --recursive --detailed
```

**Options:**
- `--pattern`: File pattern to match (glob syntax)
- `--exclude`: Pattern to exclude files
- `--recursive`: Search subdirectories
- `--detailed`: Show detailed statistics

#### 📊 fx size - Size Analyzer

Analyze file and directory sizes with flexible output options.

```bash
# Show top 10 largest files
fx size . --limit 10

# Display sizes in MB
fx size . --unit MB

# Sort by size ascending
fx size . --sort asc

# Include hidden files
fx size . --all
```

**Options:**
- `--limit`: Number of results to show
- `--unit`: Size unit (B, KB, MB, GB)
- `--sort`: Sort order (asc/desc)
- `--all`: Include hidden files

#### 🎯 fx filter - File Filter (NEW in v1.2.0!)

Filter files by extension with intelligent sorting capabilities.

```bash
# Find Python files sorted by creation time
fx filter . py

# Multiple extensions
fx filter . "jpg,png,gif" --format detailed

# Sort by modification time, newest first
fx filter ~/Documents pdf --sort-by mtime --reverse

# Non-recursive search with count
fx filter . txt --no-recursive --format count
```

**Options:**
- `--sort-by`: Sort by 'ctime' (creation) or 'mtime' (modification)
- `--reverse`: Reverse sort order (newest first)
- `--format`: Output format (simple/detailed/count)
- `--no-recursive`: Don't search subdirectories

**Output Formats:**
- **simple**: Just file paths
- **detailed**: Includes timestamp and relative time
- **count**: Summary statistics

#### 🔍 fx ff - File Finder

Find files whose names contain a keyword, with powerful filtering options and smart exclusions.

```bash
# Basic usage: Find files containing "test" in their names
fx ff test

# Find configuration files
fx ff config

# Find all Python files (using partial match)
fx ff .py

# Include normally ignored directories (.git, .venv, node_modules)
fx ff test --include-ignored

# Exclude specific directories or patterns
fx ff test --exclude build --exclude "*.log"

# Complex filtering example: find "api" files but exclude build and cache directories
fx ff api --exclude build --exclude cache --exclude "*.pyc"

# Find source files while excluding test directories
fx ff src --exclude "*test*" --exclude "*spec*"

# Case-sensitive search for specific components
fx ff Component --exclude node_modules
```

**Real-World Use Cases:**

```bash
# Development workflow: Find all TODO comments in code files
fx ff TODO --exclude node_modules --exclude .git

# Project cleanup: Find all backup files
fx ff .bak

# Debug logging: Find all log files
fx ff .log --exclude archive

# Configuration management: Find all config files across subdirectories
fx ff config --exclude backup

# Library hunting: Find specific library files
fx ff jquery --exclude node_modules --exclude dist

# Testing: Find test files but exclude coverage reports
fx ff test --exclude coverage --exclude .nyc_output
```

**Options:**
- `--include-ignored`: Include `.git`, `.venv`, `node_modules` (default skips these heavy directories)
- `--exclude NAME`: Exclude names or glob patterns; repeatable for complex filtering

#### 🔄 fx replace - Text Replacer

Safely replace text across multiple files with preview and backup options.

```bash
# Preview changes without applying
fx replace . "old_text" "new_text" --preview

# Create backups before replacing
fx replace . "v1.0" "v2.0" --backup

# Exclude certain patterns
fx replace . "foo" "bar" --exclude "*.min.js"

# Interactive mode
fx replace . "test" "production" --interactive
```

**Options:**
- `--preview`: Show changes without applying
- `--backup`: Create .bak files
- `--exclude`: Exclude file patterns
- `--interactive`: Confirm each replacement

**Safety Features:**
- Always preview changes first
- Automatic backup creation available
- Pattern exclusion for sensitive files
- Dry-run mode for testing

#### 📈 fx json2excel - JSON to Excel Converter

Convert JSON files to Excel spreadsheets.

```bash
# Basic conversion
fx json2excel data.json output.xlsx

# With custom sheet name
fx json2excel data.json report.xlsx --sheet "Results"

# Pretty formatting
fx json2excel data.json output.xlsx --pretty
```

**Options:**
- `--sheet`: Excel sheet name
- `--pretty`: Apply formatting

#### 📅 fx today - Daily Workspace Manager

Create and navigate to date-organized workspace directories for daily file management.

```bash
# Navigate to today's workspace (~/Downloads/YYYYMMDD)
fx today

# Custom base directory
fx today --base ~/Projects

# Custom date format
fx today --format %Y-%m-%d  # Creates ~/Downloads/2025-09-06

# Output path for shell scripts
fx today --cd

# Dry run to see what would be created
fx today --dry-run

# Verbose output
fx today --verbose
```

**Options:**
- `--cd, -c`: Output path only (for shell integration)
- `--base, -b`: Base directory (default: ~/Downloads)
- `--format, -f`: Date format string (default: %Y%m%d)
- `--verbose, -v`: Show detailed output
- `--dry-run`: Preview without creating directory

**Shell Integration:**
With proper setup, `fx today` can change your shell directory:
```bash
# After running setup script
$ fx today
📅 Changed to today's workspace: /Users/you/Downloads/20250906

# Or use aliases
$ ft  # Short alias for fx today
```

See [fx-today-setup.md](docs/fx-today-setup.md) for shell integration setup.

## 📚 Usage Examples

### Real-World Scenarios

#### 1. Project Cleanup
```bash
# Find and count test files
fx files . --pattern "*test*.py"

# Identify large log files
fx size . --pattern "*.log" --limit 5 --unit MB

# Remove old backup files
fx ff . ".bak" | xargs rm -f
```

#### 2. Codebase Analysis
```bash
# Count source files by type
fx filter . "py,js,ts,jsx,tsx" --format count

# Find TODO comments
fx ff . "TODO" --extension "py,js"

# Update version strings
fx replace . "version='1.1.0'" "version='1.2.0'" --preview
```

#### 3. Data Processing
```bash
# Find recent data files
fx filter ./data csv --sort-by mtime --reverse --limit 10

# Convert JSON reports to Excel
fx json2excel report.json summary.xlsx

# Analyze dataset sizes
fx size ./datasets --unit GB
```

#### 4. System Maintenance
```bash
# Find old log files
fx filter /var/log "log,txt" --sort-by mtime --format detailed

# Count configuration files
fx files /etc --pattern "*.conf"

# Search for error patterns
fx ff /var/log "ERROR" --ignore-case
```

## 🔧 Development

### Setting Up Development Environment

```bash
# Clone the repository
git clone https://github.com/frankyxhl/fx_bin.git
cd fx_bin

# Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -
# or: pipx install poetry

# Install dependencies
poetry install --with dev

# Activate virtual environment
poetry shell
```

### Running Tests

```bash
# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=fx_bin --cov-report=html

# Run specific test file
poetry run pytest tests/test_filter.py -v

# Run security tests
poetry run pytest tests/test_*security*.py -v
```

### Code Quality

```bash
# Format code
poetry run black fx_bin/ tests/

# Lint code
poetry run flake8 fx_bin/

# Type checking
poetry run mypy fx_bin/

# Security scan
poetry run bandit -r fx_bin/
```

### Building and Publishing

```bash
# Build package
poetry build

# Test installation
pip install dist/fx_bin-*.whl  # or: poetry run fx --help

# Publish to PyPI
poetry publish
```

## 🧪 Testing

fx-bin follows a comprehensive testing strategy:

### Testing Methodology
- **TDD (Test-Driven Development)**: All features developed with tests first
- **BDD (Behavior-Driven Development)**: User scenarios tested with Gherkin syntax
- **Coverage**: Maintaining 95%+ code coverage
- **CI/CD**: Automated testing on every commit

### Test Categories
- **Unit Tests**: Individual function testing
- **Integration Tests**: Component interaction testing
- **Security Tests**: Vulnerability and safety testing
- **Performance Tests**: Benchmarking and optimization
- **Edge Cases**: Boundary and error condition testing

### Running Different Test Suites

```bash
# Fast unit tests only
poetry run pytest -m "not slow"

# Security tests only
poetry run pytest -m security

# Integration tests
poetry run pytest -m integration

# Performance benchmarks
poetry run pytest -m performance
```

## 🔒 Security

### Security Features

- **Path Traversal Protection**: All file operations validate paths
- **Input Sanitization**: User inputs are cleaned and validated
- **Safe Defaults**: Conservative defaults prevent accidents
- **Command Injection Prevention**: No shell execution with user input
- **Regular Security Audits**: Automated scanning with bandit and safety

### Security Testing

```bash
# Run security test suite
poetry run pytest tests/test_*security*.py -v

# Static security analysis
poetry run bandit -r fx_bin/

# Dependency vulnerability check
poetry run safety check
```

### Reporting Security Issues

If you discover a security vulnerability, please email frank@frankxu.me directly instead of opening a public issue.

## 🤝 Contributing

We welcome contributions! Here's how to get started:

### Development Process

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Write tests for your feature
4. Implement the feature
5. Ensure all tests pass (`poetry run pytest`)
6. Check code quality (`poetry run black . && poetry run flake8`)
7. Commit your changes (`git commit -m 'Add amazing feature'`)
8. Push to the branch (`git push origin feature/amazing-feature`)
9. Open a Pull Request

### Guidelines

- Follow PEP 8 style guide
- Add tests for new features
- Update documentation
- Keep commits atomic and descriptive
- Ensure CI passes before requesting review

### Areas for Contribution

- New file operation commands
- Performance improvements
- Documentation enhancements
- Bug fixes
- Test coverage improvements
- Platform-specific optimizations

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Click](https://click.palletsprojects.com/) for elegant CLI creation
- Testing powered by [pytest](https://pytest.org/)
- Code formatting by [Black](https://black.readthedocs.io/)

## 📞 Contact

- Author: Frank Xu
- Email: frank@frankxu.me
- GitHub: [@frankyxhl](https://github.com/frankyxhl)
- PyPI: [fx-bin](https://pypi.org/project/fx-bin/)

---

**Made with ❤️ by Frank Xu**

*For more information, visit the [GitHub repository](https://github.com/frankyxhl/fx_bin)*


            

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/e3/f2/672f2a4b22d8ac9eda0c903f124819bde4d02c1464875d9ce21d3012cb1d/fx_bin-1.4.0.tar.gz",
    "platform": null,
    "description": "# fx-bin\n\n[![PyPI version](https://badge.fury.io/py/fx-bin.svg)](https://badge.fury.io/py/fx-bin)\n[![Python](https://img.shields.io/pypi/pyversions/fx-bin.svg)](https://pypi.org/project/fx-bin/)\n[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/frankyxhl/fx_bin)\n[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)](https://github.com/frankyxhl/fx_bin)\n[![Security](https://img.shields.io/badge/security-A+-brightgreen.svg)](https://github.com/frankyxhl/fx_bin)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n**A powerful, secure, and well-tested collection of Python file operation utilities with a unified CLI.**\n\n## \ud83d\udccb Table of Contents\n\n- [Why fx-bin?](#-why-fx-bin)\n- [Features](#-features)\n- [Quick Start](#-quick-start)\n- [Installation](#-installation)\n- [Commands](#-commands)\n- [Usage Examples](#-usage-examples)\n- [Development](#-development)\n- [Testing](#-testing)\n- [Security](#-security)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## \ud83e\udd14 Why fx-bin?\n\n**fx-bin** addresses common pain points in file operations:\n\n- **Unified Interface**: One command (`fx`) for all file operations - no need to remember multiple tools\n- **Safety First**: Built-in safeguards prevent accidental data loss (especially in `fx replace`)\n- **Performance**: Optimized algorithms handle large directories and files efficiently\n- **Cross-Platform**: Works seamlessly on Windows, macOS, and Linux\n- **Developer Friendly**: Comprehensive testing (95%+ coverage) and clean, maintainable code\n- **Security Focused**: Regular security audits, safe path handling, and input validation\n- **Modern Python**: Built with Python 3.11+ features and best practices\n\nWhether you're organizing files, analyzing disk usage, performing bulk text replacements, or filtering files by type, fx-bin provides a reliable, fast, and safe solution.\n\n## \u2728 Features\n\n### Core Capabilities\n\n- \ud83d\udcc1 **File Counting** - Quickly count files in directories with pattern matching\n- \ud83d\udcca **Size Analysis** - Analyze file and directory sizes with human-readable output\n- \ud83d\udd0d **File Finding** - Search for files by keywords with multiple search strategies\n- \ud83c\udfaf **File Filtering** - Filter files by extension with intelligent sorting (NEW in v1.2.0!)\n- \ud83d\udd04 **Text Replacement** - Safe, bulk text replacement across files with backup options\n- \ud83d\udcc8 **JSON to Excel** - Convert JSON data to Excel spreadsheets\n- \ud83d\udccb **Command Listing** - Built-in help and command discovery\n\n### Technical Excellence\n\n- \ud83d\udee1\ufe0f **Security Hardened** - Protection against path traversal, command injection, and other vulnerabilities\n- \u2705 **Thoroughly Tested** - TDD/BDD methodology with 95%+ test coverage\n- \ud83d\ude80 **High Performance** - Optimized for large-scale operations\n- \ud83d\udd27 **Extensible** - Clean architecture for easy feature additions\n- \ud83d\udcdd **Well Documented** - Comprehensive documentation and examples\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Install fx-bin\npip install fx-bin  # or: pipx install fx-bin\n\n# Show help and available commands\nfx help              # Same as fx -h\nfx list              # Show all available commands\n\n# Count Python files\nfx files . --pattern \"*.py\"\n\n# Find large files\nfx size . --limit 10 --unit MB\n\n# Filter documents by extension\nfx filter ~/Documents \"pdf,docx\" --format detailed\n\n# Find files containing keyword\nfx ff . \"TODO\"\n\n# Safe text replacement\nfx replace . \"old_text\" \"new_text\" --preview\n```\n\n## \ud83d\udce6 Installation\n\n### Via pip (Recommended)\n\n```bash\npip install fx-bin\n```\n\n### Via pipx (For Isolated Installation)\n\n```bash\npipx install fx-bin\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/frankyxhl/fx_bin.git\ncd fx_bin\npoetry install\npoetry run fx --help\n```\n\n### Requirements\n\n- Python 3.11 or higher\n- No external dependencies required for core functionality\n- Optional: pandas for Excel operations (`pip install fx-bin[excel]`)\n\n## \ud83d\udee0\ufe0f Commands\n\n### Overview\n\n| Command | Description | Key Features |\n|---------|-------------|--------------|\n| `fx files` | Count files in directories | Pattern matching, recursive search, detailed stats |\n| `fx size` | Analyze file/directory sizes | Human-readable units, sorting, limit results |\n| `fx ff` | Find files by keyword | Multiple search modes, content search, regex support |\n| `fx filter` | Filter files by extension | Time-based sorting, multiple formats, recursive search |\n| `fx replace` | Replace text in files | Preview mode, backup creation, pattern exclusion |\n| `fx json2excel` | Convert JSON to Excel | Automatic formatting, multiple sheets |\n| `fx list` | List all available commands | Help and usage information |\n\n### Detailed Command Documentation\n\n#### \ud83d\udcc1 fx files - File Counter\n\nCount files in directories with powerful filtering options.\n\n```bash\n# Basic usage\nfx files /path/to/directory\n\n# Count only Python files\nfx files . --pattern \"*.py\"\n\n# Exclude test files\nfx files . --exclude \"*test*\"\n\n# Recursive search with details\nfx files . --recursive --detailed\n```\n\n**Options:**\n- `--pattern`: File pattern to match (glob syntax)\n- `--exclude`: Pattern to exclude files\n- `--recursive`: Search subdirectories\n- `--detailed`: Show detailed statistics\n\n#### \ud83d\udcca fx size - Size Analyzer\n\nAnalyze file and directory sizes with flexible output options.\n\n```bash\n# Show top 10 largest files\nfx size . --limit 10\n\n# Display sizes in MB\nfx size . --unit MB\n\n# Sort by size ascending\nfx size . --sort asc\n\n# Include hidden files\nfx size . --all\n```\n\n**Options:**\n- `--limit`: Number of results to show\n- `--unit`: Size unit (B, KB, MB, GB)\n- `--sort`: Sort order (asc/desc)\n- `--all`: Include hidden files\n\n#### \ud83c\udfaf fx filter - File Filter (NEW in v1.2.0!)\n\nFilter files by extension with intelligent sorting capabilities.\n\n```bash\n# Find Python files sorted by creation time\nfx filter . py\n\n# Multiple extensions\nfx filter . \"jpg,png,gif\" --format detailed\n\n# Sort by modification time, newest first\nfx filter ~/Documents pdf --sort-by mtime --reverse\n\n# Non-recursive search with count\nfx filter . txt --no-recursive --format count\n```\n\n**Options:**\n- `--sort-by`: Sort by 'ctime' (creation) or 'mtime' (modification)\n- `--reverse`: Reverse sort order (newest first)\n- `--format`: Output format (simple/detailed/count)\n- `--no-recursive`: Don't search subdirectories\n\n**Output Formats:**\n- **simple**: Just file paths\n- **detailed**: Includes timestamp and relative time\n- **count**: Summary statistics\n\n#### \ud83d\udd0d fx ff - File Finder\n\nFind files whose names contain a keyword, with powerful filtering options and smart exclusions.\n\n```bash\n# Basic usage: Find files containing \"test\" in their names\nfx ff test\n\n# Find configuration files\nfx ff config\n\n# Find all Python files (using partial match)\nfx ff .py\n\n# Include normally ignored directories (.git, .venv, node_modules)\nfx ff test --include-ignored\n\n# Exclude specific directories or patterns\nfx ff test --exclude build --exclude \"*.log\"\n\n# Complex filtering example: find \"api\" files but exclude build and cache directories\nfx ff api --exclude build --exclude cache --exclude \"*.pyc\"\n\n# Find source files while excluding test directories\nfx ff src --exclude \"*test*\" --exclude \"*spec*\"\n\n# Case-sensitive search for specific components\nfx ff Component --exclude node_modules\n```\n\n**Real-World Use Cases:**\n\n```bash\n# Development workflow: Find all TODO comments in code files\nfx ff TODO --exclude node_modules --exclude .git\n\n# Project cleanup: Find all backup files\nfx ff .bak\n\n# Debug logging: Find all log files\nfx ff .log --exclude archive\n\n# Configuration management: Find all config files across subdirectories\nfx ff config --exclude backup\n\n# Library hunting: Find specific library files\nfx ff jquery --exclude node_modules --exclude dist\n\n# Testing: Find test files but exclude coverage reports\nfx ff test --exclude coverage --exclude .nyc_output\n```\n\n**Options:**\n- `--include-ignored`: Include `.git`, `.venv`, `node_modules` (default skips these heavy directories)\n- `--exclude NAME`: Exclude names or glob patterns; repeatable for complex filtering\n\n#### \ud83d\udd04 fx replace - Text Replacer\n\nSafely replace text across multiple files with preview and backup options.\n\n```bash\n# Preview changes without applying\nfx replace . \"old_text\" \"new_text\" --preview\n\n# Create backups before replacing\nfx replace . \"v1.0\" \"v2.0\" --backup\n\n# Exclude certain patterns\nfx replace . \"foo\" \"bar\" --exclude \"*.min.js\"\n\n# Interactive mode\nfx replace . \"test\" \"production\" --interactive\n```\n\n**Options:**\n- `--preview`: Show changes without applying\n- `--backup`: Create .bak files\n- `--exclude`: Exclude file patterns\n- `--interactive`: Confirm each replacement\n\n**Safety Features:**\n- Always preview changes first\n- Automatic backup creation available\n- Pattern exclusion for sensitive files\n- Dry-run mode for testing\n\n#### \ud83d\udcc8 fx json2excel - JSON to Excel Converter\n\nConvert JSON files to Excel spreadsheets.\n\n```bash\n# Basic conversion\nfx json2excel data.json output.xlsx\n\n# With custom sheet name\nfx json2excel data.json report.xlsx --sheet \"Results\"\n\n# Pretty formatting\nfx json2excel data.json output.xlsx --pretty\n```\n\n**Options:**\n- `--sheet`: Excel sheet name\n- `--pretty`: Apply formatting\n\n#### \ud83d\udcc5 fx today - Daily Workspace Manager\n\nCreate and navigate to date-organized workspace directories for daily file management.\n\n```bash\n# Navigate to today's workspace (~/Downloads/YYYYMMDD)\nfx today\n\n# Custom base directory\nfx today --base ~/Projects\n\n# Custom date format\nfx today --format %Y-%m-%d  # Creates ~/Downloads/2025-09-06\n\n# Output path for shell scripts\nfx today --cd\n\n# Dry run to see what would be created\nfx today --dry-run\n\n# Verbose output\nfx today --verbose\n```\n\n**Options:**\n- `--cd, -c`: Output path only (for shell integration)\n- `--base, -b`: Base directory (default: ~/Downloads)\n- `--format, -f`: Date format string (default: %Y%m%d)\n- `--verbose, -v`: Show detailed output\n- `--dry-run`: Preview without creating directory\n\n**Shell Integration:**\nWith proper setup, `fx today` can change your shell directory:\n```bash\n# After running setup script\n$ fx today\n\ud83d\udcc5 Changed to today's workspace: /Users/you/Downloads/20250906\n\n# Or use aliases\n$ ft  # Short alias for fx today\n```\n\nSee [fx-today-setup.md](docs/fx-today-setup.md) for shell integration setup.\n\n## \ud83d\udcda Usage Examples\n\n### Real-World Scenarios\n\n#### 1. Project Cleanup\n```bash\n# Find and count test files\nfx files . --pattern \"*test*.py\"\n\n# Identify large log files\nfx size . --pattern \"*.log\" --limit 5 --unit MB\n\n# Remove old backup files\nfx ff . \".bak\" | xargs rm -f\n```\n\n#### 2. Codebase Analysis\n```bash\n# Count source files by type\nfx filter . \"py,js,ts,jsx,tsx\" --format count\n\n# Find TODO comments\nfx ff . \"TODO\" --extension \"py,js\"\n\n# Update version strings\nfx replace . \"version='1.1.0'\" \"version='1.2.0'\" --preview\n```\n\n#### 3. Data Processing\n```bash\n# Find recent data files\nfx filter ./data csv --sort-by mtime --reverse --limit 10\n\n# Convert JSON reports to Excel\nfx json2excel report.json summary.xlsx\n\n# Analyze dataset sizes\nfx size ./datasets --unit GB\n```\n\n#### 4. System Maintenance\n```bash\n# Find old log files\nfx filter /var/log \"log,txt\" --sort-by mtime --format detailed\n\n# Count configuration files\nfx files /etc --pattern \"*.conf\"\n\n# Search for error patterns\nfx ff /var/log \"ERROR\" --ignore-case\n```\n\n## \ud83d\udd27 Development\n\n### Setting Up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/frankyxhl/fx_bin.git\ncd fx_bin\n\n# Install Poetry (if not already installed)\ncurl -sSL https://install.python-poetry.org | python3 -\n# or: pipx install poetry\n\n# Install dependencies\npoetry install --with dev\n\n# Activate virtual environment\npoetry shell\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npoetry run pytest\n\n# Run with coverage\npoetry run pytest --cov=fx_bin --cov-report=html\n\n# Run specific test file\npoetry run pytest tests/test_filter.py -v\n\n# Run security tests\npoetry run pytest tests/test_*security*.py -v\n```\n\n### Code Quality\n\n```bash\n# Format code\npoetry run black fx_bin/ tests/\n\n# Lint code\npoetry run flake8 fx_bin/\n\n# Type checking\npoetry run mypy fx_bin/\n\n# Security scan\npoetry run bandit -r fx_bin/\n```\n\n### Building and Publishing\n\n```bash\n# Build package\npoetry build\n\n# Test installation\npip install dist/fx_bin-*.whl  # or: poetry run fx --help\n\n# Publish to PyPI\npoetry publish\n```\n\n## \ud83e\uddea Testing\n\nfx-bin follows a comprehensive testing strategy:\n\n### Testing Methodology\n- **TDD (Test-Driven Development)**: All features developed with tests first\n- **BDD (Behavior-Driven Development)**: User scenarios tested with Gherkin syntax\n- **Coverage**: Maintaining 95%+ code coverage\n- **CI/CD**: Automated testing on every commit\n\n### Test Categories\n- **Unit Tests**: Individual function testing\n- **Integration Tests**: Component interaction testing\n- **Security Tests**: Vulnerability and safety testing\n- **Performance Tests**: Benchmarking and optimization\n- **Edge Cases**: Boundary and error condition testing\n\n### Running Different Test Suites\n\n```bash\n# Fast unit tests only\npoetry run pytest -m \"not slow\"\n\n# Security tests only\npoetry run pytest -m security\n\n# Integration tests\npoetry run pytest -m integration\n\n# Performance benchmarks\npoetry run pytest -m performance\n```\n\n## \ud83d\udd12 Security\n\n### Security Features\n\n- **Path Traversal Protection**: All file operations validate paths\n- **Input Sanitization**: User inputs are cleaned and validated\n- **Safe Defaults**: Conservative defaults prevent accidents\n- **Command Injection Prevention**: No shell execution with user input\n- **Regular Security Audits**: Automated scanning with bandit and safety\n\n### Security Testing\n\n```bash\n# Run security test suite\npoetry run pytest tests/test_*security*.py -v\n\n# Static security analysis\npoetry run bandit -r fx_bin/\n\n# Dependency vulnerability check\npoetry run safety check\n```\n\n### Reporting Security Issues\n\nIf you discover a security vulnerability, please email frank@frankxu.me directly instead of opening a public issue.\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Development Process\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Write tests for your feature\n4. Implement the feature\n5. Ensure all tests pass (`poetry run pytest`)\n6. Check code quality (`poetry run black . && poetry run flake8`)\n7. Commit your changes (`git commit -m 'Add amazing feature'`)\n8. Push to the branch (`git push origin feature/amazing-feature`)\n9. Open a Pull Request\n\n### Guidelines\n\n- Follow PEP 8 style guide\n- Add tests for new features\n- Update documentation\n- Keep commits atomic and descriptive\n- Ensure CI passes before requesting review\n\n### Areas for Contribution\n\n- New file operation commands\n- Performance improvements\n- Documentation enhancements\n- Bug fixes\n- Test coverage improvements\n- Platform-specific optimizations\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with [Click](https://click.palletsprojects.com/) for elegant CLI creation\n- Testing powered by [pytest](https://pytest.org/)\n- Code formatting by [Black](https://black.readthedocs.io/)\n\n## \ud83d\udcde Contact\n\n- Author: Frank Xu\n- Email: frank@frankxu.me\n- GitHub: [@frankyxhl](https://github.com/frankyxhl)\n- PyPI: [fx-bin](https://pypi.org/project/fx-bin/)\n\n---\n\n**Made with \u2764\ufe0f by Frank Xu**\n\n*For more information, visit the [GitHub repository](https://github.com/frankyxhl/fx_bin)*\n\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A common bin collection for my own usage",
    "version": "1.4.0",
    "project_urls": {
        "Repository": "https://github.com/frankyxhl/fx_bin"
    },
    "split_keywords": [
        "fx_bin"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "5cb19d0c1d7d4c07a9df9a2013479f7760486b883f78bb5a58649a4b62ae4854",
                "md5": "2f9589afa345de7284248b3765c3bbc5",
                "sha256": "dfb43e16e4b73950368ab407920b0782ea49468c81c99395aad001190c0493bf"
            },
            "downloads": -1,
            "filename": "fx_bin-1.4.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2f9589afa345de7284248b3765c3bbc5",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.11",
            "size": 36820,
            "upload_time": "2025-09-07T00:17:09",
            "upload_time_iso_8601": "2025-09-07T00:17:09.432390Z",
            "url": "https://files.pythonhosted.org/packages/5c/b1/9d0c1d7d4c07a9df9a2013479f7760486b883f78bb5a58649a4b62ae4854/fx_bin-1.4.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "e3f2672f2a4b22d8ac9eda0c903f124819bde4d02c1464875d9ce21d3012cb1d",
                "md5": "becb150d367c0a1d49dc9ec517437f93",
                "sha256": "08677d66df522d491b8d3a3157a7a76d954bdf0348f524f3a58dcf881f1be132"
            },
            "downloads": -1,
            "filename": "fx_bin-1.4.0.tar.gz",
            "has_sig": false,
            "md5_digest": "becb150d367c0a1d49dc9ec517437f93",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.11",
            "size": 34627,
            "upload_time": "2025-09-07T00:17:10",
            "upload_time_iso_8601": "2025-09-07T00:17:10.548290Z",
            "url": "https://files.pythonhosted.org/packages/e3/f2/672f2a4b22d8ac9eda0c903f124819bde4d02c1464875d9ce21d3012cb1d/fx_bin-1.4.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-09-07 00:17:10",
    "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"
}