Metadata-Version: 2.4
Name: pychkr
Version: 0.1.1
Summary: A powerful Python utility for checking port availability, monitoring port status, and diagnosing network services on your local system.
Home-page: https://github.com/KidiXDev/port-checker
Author: KidiXDev
Author-email: KidiXDev <kidixdev@logiclab.id>
License: MIT License
        
        Copyright (c) 2025 KidiXDev
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file

# PyChkr

A powerful Python utility for checking port availability, monitoring port status, and diagnosing network services on your local system.

## Features

- Check port availability in ranges or specific ports
- Detailed service information and port status
- Real-time port monitoring
- Common service ports quick check
- Export results to JSON
- Find available ports automatically
- Command-line interface with rich output

## Installation

```bash
# Install from PyPI
pip install pychkr

# Or install from source
git clone https://github.com/KidiXDev/port-checker.git
cd port-checker
pip install .
```

## Quick Start

```bash
# Find first available port in default range (8000-9000)
pychkr

# Check if specific ports are available
pychkr --check 80,443,8080

# Scan a range and list all ports
pychkr --range 3000-3100 --list

# Check common service ports
pychkr --common
```

## Usage

### Basic Commands

**Find first available port:**

```bash
pychkr --range 8000-9000
```

**Check specific ports:**

```bash
pychkr --check 80,443,3306,5432
```

**Check port ranges:**

```bash
pychkr --check 8000-8010,9000-9005
```

### Scanning & Listing

**List all available and used ports:**

```bash
pychkr --range 3000-3100 --list
```

**Show detailed information (with service names):**

```bash
pychkr --range 8000-8050 --list --detailed
```

**Find multiple available ports:**

```bash
pychkr --range 3000-4000 --count 5
```

### Common Ports Check

Check standard service ports (HTTP, HTTPS, SSH, MySQL, PostgreSQL, Redis, etc.):

```bash
pychkr --common
```

### Monitoring

Monitor ports for changes over time:

```bash
# Monitor ports every 5 seconds for 60 seconds
pychkr --monitor 8000,8080,3000

# Custom interval and duration
pychkr --monitor 80,443 --interval 10 --duration 300
```

### Export Results

Save scan results to JSON:

```bash
pychkr --range 8000-9000 --list --export results.json
pychkr --common --export common-ports.json
```

## Options

| Option              | Description                                  |
| ------------------- | -------------------------------------------- |
| `--range START-END` | Port range to check (e.g., 8000-9000)        |
| `--check PORTS`     | Check specific ports (comma-separated)       |
| `--common`          | Check common service ports                   |
| `--list`            | List all available and used ports            |
| `--detailed`        | Show detailed information with service names |
| `--count N`         | Find N available ports                       |
| `--monitor PORTS`   | Monitor ports for changes                    |
| `--interval SEC`    | Monitoring check interval (default: 5)       |
| `--duration SEC`    | Monitoring duration (default: 60)            |
| `--host HOST`       | Host address to bind to (default: 0.0.0.0)   |
| `--export FILE`     | Export results to JSON file                  |

## Examples

**DevOps scenario - Find ports for microservices:**

```bash
pychkr --range 8000-8100 --count 10
```

**Troubleshooting - Check if services are running:**

```bash
pychkr --common --detailed
```

**Development - Monitor port during deployment:**

```bash
pychkr --monitor 3000,8080 --interval 5 --duration 120
```

**Security audit - Scan for open ports:**

```bash
pychkr --range 1-1024 --list --detailed --export scan-results.json
```

**Quick check before starting a server:**

```bash
pychkr --check 8000,8080,3000
```

## Output Examples

### Simple check:

```
First available port: 8000
```

### Detailed scan:

```
==================================================
Available Ports (45)
==================================================
  8000
  8001
  8002
  ...

==================================================
Used Ports (5)
==================================================
  8080 (http-alt) [listening]
  3306 (mysql) [in use]
  ...

Summary: 45 available, 5 in use
```

### Common ports check:

```
Port     Service              Status          Listening
============================================================
22       SSH                  ✓ available     ○
80       HTTP                 ✗ in use        ●
443      HTTPS                ✓ available     ○
3306     MySQL                ✗ listening     ●
...
```

## Use Cases

- Development: Find available ports for local services
- DevOps: Verify port availability before deployments
- Troubleshooting: Diagnose port conflicts
- Monitoring: Track port status over time
- Security: Audit open ports on systems
- CI/CD: Automated port checking in pipelines

## Requirements

1. Clone the repository:

   ```bash
   git clone https://github.com/KidiXDev/port-checker.git
   cd port-checker
   ```

2. Install in development mode:

   ```bash
   pip install -e .
   ```

3. Run tests:
   ```bash
   python -m unittest discover tests
   ```

## License

MIT License - See [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Author

KidiXDev - [@KidiXDev](https://github.com/KidiXDev)

## Support

If you find this project useful, please consider giving it a ⭐️ on GitHub.

## Version

Current version: 0.1.0
