wtfport 0.1.0__tar.gz

wtfport-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: wtfport
+Version: 0.1.0
+Summary: CLI tool to watch system port usage
+Author-email: Henry <henry@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourname/wtfport
+Project-URL: Issues, https://github.com/yourname/wtfport/issues
+Keywords: ports,network,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: psutil
+Requires-Dist: click
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# wtfport
+
+A terminal-based tool that provides developers with an intuitive, human-friendly way to identify, inspect, and interact with processes bound to specific ports on their system.
+
+![wtfport demo](https://raw.githubusercontent.com/hungwahenry/wtfport/main/docs/demo.gif)
+
+## Features
+
+- **Port Lookup**: Quickly show details about the process using a specific port
+- **Process Management**: Kill a process running on a port with a simple command
+- **Cross-Platform Support**: Available for macOS, Linux, and Windows
+- **Colorized Output**: Clear, visually appealing terminal output
+- **Watch Mode**: Continuously monitor and update port usage
+- **Interactive Mode**: Simple interface for interacting with processes
+- **Clipboard Support**: Copy process commands directly to clipboard
+- **Web Server Detection**: Quick access to open web servers in browser
+- **Log Tailing**: Ability to detect and tail logs for processes
+- **Port Statistics**: Track and analyze your most frequently used ports
+- **Notifications**: Get alerted when a specific port becomes active
+
+## Installation
+
+### Using pip
+
+```bash
+pip install wtfport
+```
+
+### Using Homebrew (macOS/Linux)
+
+```bash
+brew install wtfport
+```
+
+### From Source
+
+```bash
+git clone https://github.com/yourusername/wtfport.git
+cd wtfport
+pip install -e .
+```
+
+## Usage
+
+### Basic Commands
+
+Check a specific port:
+```bash
+wtfport 3000
+```
+
+Show all listening ports:
+```bash
+wtfport
+# or
+wtfport --all
+```
+
+Kill a process on a port:
+```bash
+wtfport 3000 --kill
+```
+
+### Monitoring Features
+
+Watch a port for changes:
+```bash
+wtfport 3000 --watch
+```
+
+Get notified when a port becomes active:
+```bash
+wtfport --notify 5000
+```
+
+### For Web Developers
+
+Open a web server in browser:
+```bash
+wtfport 3000 --open
+```
+
+### Port Statistics and History
+
+View port usage statistics:
+```bash
+wtfport --stats
+```
+
+View detailed history for a specific port:
+```bash
+wtfport --stats-detail 3000
+```
+
+### Automation & Scripting
+
+Get JSON output for scripting:
+```bash
+wtfport 3000 --json
+```
+
+Copy the command to clipboard:
+```bash
+wtfport 3000 --copy
+```
+
+### Interactive Mode
+
+When running `wtfport <port>` without additional flags, you'll enter interactive mode where you can:
+
+- Open the port in a browser
+- Kill the process
+- Copy the command to clipboard
+- Tail logs (if available)
+
+## Examples
+
+### Finding What's Using a Port
+
+```bash
+$ wtfport 3000
+
+Port 3000 is being used by:
+╭──────────────────────────────────────────────────────────────────╮
+│                                                                  │
+│ ✓ Process:   node                                                │
+│    PID:       1234                                               │
+│    Command:   node server.js                                     │
+│    User:      yourname                                           │
+│    Started:   3m ago                                             │
+│                                                                  │
+╰──────────────────────────────────────────────────────────────────╯
+
+Options:
+[O] Open in browser      (http://localhost:3000)
+[K] Kill process         (sudo may be required)
+[C] Copy command         (to clipboard)
+[Q] Quit
+```
+
+### Viewing All Listening Ports
+
+```bash
+$ wtfport
+
+Listening Ports:
+┏━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━┓
+┃  Port ┃ Process       ┃   PID ┃ User      ┃ Started     ┃
+┡━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━┩
+│   22  │ sshd          │   122 │ root      │ 4h ago      │
+│  443  │ httpd         │   436 │ www       │ 2d ago      │
+│ 3000  │ node          │  1234 │ yourname  │ 3m ago      │
+│ 5432  │ postgres      │   983 │ postgres  │ 2d ago      │
+└───────┴───────────────┴───────┴───────────┴─────────────┘
+
+Tip: run `wtfport <port>` to inspect in detail.
+```
+
+### Port Statistics
+
+```bash
+$ wtfport --stats
+
+Port Usage Statistics:
+
+Tracking data for 15 ports and 7 processes.
+Last updated: 2023-06-15T14:30:22.456789
+
+Top Ports:
+┏━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
+┃  Port ┃ Access Count ┃ Processes                  ┃ Last Seen    ┃
+┡━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
+│ 3000  │ 42           │ node, python, ruby         │ 2023-06-15   │
+│ 8080  │ 27           │ java, tomcat               │ 2023-06-14   │
+│ 5432  │ 18           │ postgres                   │ 2023-06-15   │
+│ 443   │ 15           │ nginx, apache              │ 2023-06-15   │
+│ 27017 │ 10           │ mongod                     │ 2023-06-13   │
+└───────┴──────────────┴────────────────────────────┴──────────────┘
+
+Top Processes:
+┏━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Process   ┃ Access Count ┃ Used Ports                       ┃
+┡━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ node      │ 45           │ 3000, 8000, 9000, 4200, 4000     │
+│ postgres  │ 18           │ 5432                             │
+│ nginx     │ 15           │ 443, 80                          │
+│ java      │ 12           │ 8080, 8443                       │
+│ mongod    │ 10           │ 27017                            │
+└───────────┴──────────────┴─────────────────────────────────┘
+
+Tip: Use `wtfport --stats-detail <port>` to see detailed history for a specific port.
+```
+
+## Requirements
+
+- Python 3.7 or higher
+- Dependencies (automatically installed):
+  - typer
+  - rich
+  - psutil
+  - pyperclip
+
+## Privacy
+
+wtfport runs completely locally on your machine. The statistics feature stores data only in a local file (~/.wtfport/stats.json) and no data is ever sent outside your computer.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Credits
+
+Created by [Hungwa Henry](https://github.com/hungwahenry)

wtfport-0.1.0/README.md

@@ -0,0 +1,223 @@
+# wtfport
+
+A terminal-based tool that provides developers with an intuitive, human-friendly way to identify, inspect, and interact with processes bound to specific ports on their system.
+
+![wtfport demo](https://raw.githubusercontent.com/hungwahenry/wtfport/main/docs/demo.gif)
+
+## Features
+
+- **Port Lookup**: Quickly show details about the process using a specific port
+- **Process Management**: Kill a process running on a port with a simple command
+- **Cross-Platform Support**: Available for macOS, Linux, and Windows
+- **Colorized Output**: Clear, visually appealing terminal output
+- **Watch Mode**: Continuously monitor and update port usage
+- **Interactive Mode**: Simple interface for interacting with processes
+- **Clipboard Support**: Copy process commands directly to clipboard
+- **Web Server Detection**: Quick access to open web servers in browser
+- **Log Tailing**: Ability to detect and tail logs for processes
+- **Port Statistics**: Track and analyze your most frequently used ports
+- **Notifications**: Get alerted when a specific port becomes active
+
+## Installation
+
+### Using pip
+
+```bash
+pip install wtfport
+```
+
+### Using Homebrew (macOS/Linux)
+
+```bash
+brew install wtfport
+```
+
+### From Source
+
+```bash
+git clone https://github.com/yourusername/wtfport.git
+cd wtfport
+pip install -e .
+```
+
+## Usage
+
+### Basic Commands
+
+Check a specific port:
+```bash
+wtfport 3000
+```
+
+Show all listening ports:
+```bash
+wtfport
+# or
+wtfport --all
+```
+
+Kill a process on a port:
+```bash
+wtfport 3000 --kill
+```
+
+### Monitoring Features
+
+Watch a port for changes:
+```bash
+wtfport 3000 --watch
+```
+
+Get notified when a port becomes active:
+```bash
+wtfport --notify 5000
+```
+
+### For Web Developers
+
+Open a web server in browser:
+```bash
+wtfport 3000 --open
+```
+
+### Port Statistics and History
+
+View port usage statistics:
+```bash
+wtfport --stats
+```
+
+View detailed history for a specific port:
+```bash
+wtfport --stats-detail 3000
+```
+
+### Automation & Scripting
+
+Get JSON output for scripting:
+```bash
+wtfport 3000 --json
+```
+
+Copy the command to clipboard:
+```bash
+wtfport 3000 --copy
+```
+
+### Interactive Mode
+
+When running `wtfport <port>` without additional flags, you'll enter interactive mode where you can:
+
+- Open the port in a browser
+- Kill the process
+- Copy the command to clipboard
+- Tail logs (if available)
+
+## Examples
+
+### Finding What's Using a Port
+
+```bash
+$ wtfport 3000
+
+Port 3000 is being used by:
+╭──────────────────────────────────────────────────────────────────╮
+│                                                                  │
+│ ✓ Process:   node                                                │
+│    PID:       1234                                               │
+│    Command:   node server.js                                     │
+│    User:      yourname                                           │
+│    Started:   3m ago                                             │
+│                                                                  │
+╰──────────────────────────────────────────────────────────────────╯
+
+Options:
+[O] Open in browser      (http://localhost:3000)
+[K] Kill process         (sudo may be required)
+[C] Copy command         (to clipboard)
+[Q] Quit
+```
+
+### Viewing All Listening Ports
+
+```bash
+$ wtfport
+
+Listening Ports:
+┏━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━┓
+┃  Port ┃ Process       ┃   PID ┃ User      ┃ Started     ┃
+┡━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━┩
+│   22  │ sshd          │   122 │ root      │ 4h ago      │
+│  443  │ httpd         │   436 │ www       │ 2d ago      │
+│ 3000  │ node          │  1234 │ yourname  │ 3m ago      │
+│ 5432  │ postgres      │   983 │ postgres  │ 2d ago      │
+└───────┴───────────────┴───────┴───────────┴─────────────┘
+
+Tip: run `wtfport <port>` to inspect in detail.
+```
+
+### Port Statistics
+
+```bash
+$ wtfport --stats
+
+Port Usage Statistics:
+
+Tracking data for 15 ports and 7 processes.
+Last updated: 2023-06-15T14:30:22.456789
+
+Top Ports:
+┏━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
+┃  Port ┃ Access Count ┃ Processes                  ┃ Last Seen    ┃
+┡━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
+│ 3000  │ 42           │ node, python, ruby         │ 2023-06-15   │
+│ 8080  │ 27           │ java, tomcat               │ 2023-06-14   │
+│ 5432  │ 18           │ postgres                   │ 2023-06-15   │
+│ 443   │ 15           │ nginx, apache              │ 2023-06-15   │
+│ 27017 │ 10           │ mongod                     │ 2023-06-13   │
+└───────┴──────────────┴────────────────────────────┴──────────────┘
+
+Top Processes:
+┏━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Process   ┃ Access Count ┃ Used Ports                       ┃
+┡━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ node      │ 45           │ 3000, 8000, 9000, 4200, 4000     │
+│ postgres  │ 18           │ 5432                             │
+│ nginx     │ 15           │ 443, 80                          │
+│ java      │ 12           │ 8080, 8443                       │
+│ mongod    │ 10           │ 27017                            │
+└───────────┴──────────────┴─────────────────────────────────┘
+
+Tip: Use `wtfport --stats-detail <port>` to see detailed history for a specific port.
+```
+
+## Requirements
+
+- Python 3.7 or higher
+- Dependencies (automatically installed):
+  - typer
+  - rich
+  - psutil
+  - pyperclip
+
+## Privacy
+
+wtfport runs completely locally on your machine. The statistics feature stores data only in a local file (~/.wtfport/stats.json) and no data is ever sent outside your computer.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Credits
+
+Created by [Hungwa Henry](https://github.com/hungwahenry)

wtfport-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wtfport"
+version = "0.1.0"
+description = "CLI tool to watch system port usage"
+readme = "README.md"
+authors = [
+  { name="Henry", email="henry@example.com" }
+]
+license = { text = "MIT" }
+keywords = ["ports", "network", "cli"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.7",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Debuggers",
+  "Topic :: System :: Networking",
+  "Topic :: Utilities"
+]
+requires-python = ">=3.7"
+dependencies = [
+  "psutil",
+  "click"
+]
+
+[project.optional-dependencies]
+dev = ["build", "twine", "pytest"]
+
+[project.urls]
+Homepage = "https://github.com/yourname/wtfport"
+Issues = "https://github.com/yourname/wtfport/issues"
+
+[project.scripts]
+wtfport = "wtfport.cli:main"

wtfport-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wtfport-0.1.0/wtfport/__init__.py

@@ -0,0 +1,7 @@
+"""
+wtfport - A terminal tool to identify, inspect, and interact with processes bound to specific ports.
+"""
+
+from .version import __version__
+
+from wtfport.core import get_process_by_port, get_all_listening_ports, kill_process