Refactor/project layout

.github/workflows/ruff.yaml

@@ -0,0 +1,43 @@
+name: Python Code Quality Check (Ruff)
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Ruff
+        run: pip install ruff
+
+      - name: Run Ruff Check (Linting)
+        run: ruff check .
+        # if there are any issues it will exit with non-zero code.
+
+      - name: Run Ruff Format Check
+        run: ruff format --check
+        # if there are any issues it will exit with non-zero code.
+
+      - name: Show Unformatted Files For Debugging
+        if: failure()
+        run: |
+          echo "::error::Python code hasn't been formatted or has linting issues."
+          echo "Please run 'ruff check . --fix' and 'ruff format .' locally."
+          echo "Files with linting issues:"
+          ruff check . --statistics
+          echo "Files with formatting issues(diff):"
+          ruff format --check --diff .
+        # or --output-format=text to list them all

.gitignore

@@ -1,5 +1,6 @@
 .wakatime-project
 .ruff_cache/
+.flatpak-builder/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -164,3 +165,12 @@ cython_debug/
 
 /nix/result
 /result
+
+# --- Snapcraft ---
+prime/
+parts/
+stage/
+*.snap
+*.manifest
+*.assert
+*.summary

README.md

@@ -1,47 +1,121 @@
-![anifetch](anifetch.webp)
+![anifetch](docs/anifetch.webp)
 
 # Anifetch - Neofetch but animated.
 
 This is a small tool built with neofetch/fastfetch, ffmpeg and chafa. It allows you to use neofetch or fastfetch while having animations.
 
-## How to Install
-You need `bc` to be installed. For debian/ubuntu it's `apt install bc`. For Arch it's `pacman -S bc`.
+## 🛠️ How to Install
 
-You need `chafa` to be installed. For debian/ubuntu it is `apt install chafa`. [Download Instructions](https://hpjansson.org/chafa/download/)
+### Prerequisites
 
-if you don't have ffmpeg, download it here: [ffmpeg download](https://www.ffmpeg.org/download.html)
+Recommended Python version: 3.12 and later
 
-Clone the git repo.
+You need the following tools installed on your system:
 
-```cmd
-git clone https://github.com/Notenlish/anifetch
+- `bc`
+
+  - Debian/Ubuntu: `sudo apt install bc`
+  - Arch: `sudo pacman -S bc`
+
+- `chafa`
+
+  - Debian/Ubuntu: `sudo apt install chafa`
+  - [Other distros – Download Instructions](https://hpjansson.org/chafa/download/)
+
+- `ffmpeg` (for video/audio playback)
+
+  - Debian/Ubuntu: `sudo apt install ffmpeg`
+  - [Other systems – Download](https://www.ffmpeg.org/download.html)
+
+⚠️ Make sure `ffplay` is included in your `ffmpeg` installation (used for optional sound playback).
+
+---
+
+### ✅ Recommended Installation (for regular users): via `pipx`
+
+```bash
+pipx install git+https://github.com/Notenlish/anifetch.git
 ```
 
-You don't need to setup an venv or install any python modules.
+This installs `anifetch` in an isolated environment, keeping your system Python clean.
+You can then run the `anifetch` command **directly in your terminal**.
+
+✅ **Benefits**:
 
-Sound functionality is added via `ffplay`. If you install ffmpeg via a package manager like `apt` it should also install it automatically.
+- Avoids dependency conflicts.
+- Doesn’t pollute your global Python environment.
+- Behaves like a native CLI tool.
+- Easy updates with `pipx upgrade anifetch`.
 
-## How to Use It
+🔧 Make sure `pipx` is installed:
 
-Your neofetch logo file should only include a single character for the ascii art. Anifetch will attempt to find it and replace it with the chafa animation output. An example logo file can be found in `example-logo.txt`. Fastfetch doesnt need any special configuration.
+```bash
+sudo apt install pipx
+pipx ensurepath
+```
 
-An example neofetch config can be found here: `example-config.conf`
+---
 
-Simply place your video/gif file in the project folder. There's an already included test file called `video.mp4`, you can use that if you want.
+### 👨‍💻 Developer Installation (for contributors): via `pip` in a virtual environment
 
-Then run `python3 anifetch.py -f [filename] --framerate 10 --width 40 --height 20 -c "[add optional chafa arguments if you want]"`.
+```bash
+git clone https://github.com/Notenlish/anifetch.git
+cd anifetch
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
+```
 
-Here's an example command: `python3 anifetch.py -f "video.mp4" -r 10 -W 40 -H 20 -c "--symbols wide --fg-only"`
+This installs `anifetch` in **editable mode** within a local virtual environment for development.
 
-Run `python3 anifetch.py --help` if you need help.
+You can then run the program in two ways:
 
-You can also play a sound via `-s [sound filename]`.
+- As a CLI: `anifetch`
+- Or as a module: `python3 -m anifetch` (useful for debugging or internal testing)
 
-## Creating a Shortcut
+⚠️ Avoid using `pip install` outside a virtual environment on systems like Ubuntu.
+This is restricted by [PEP 668](https://peps.python.org/pep-0668/) to protect the system Python.
 
-Just add an shell alias to your `~/.bashrc` file. Example: `alias anifetch='python3 [path-to-anifetch.py] -f [path-to-video-file]'`
+## ▶️ How to Use It
 
-## Benchmarks
+You don't need to configure anything for `fastfetch` or `neofetch`. If they already work on your machine, `anifetch` will detect and integrate them automatically.
+
+Place your video or gif file anywhere (e.g. your project folder).
+By default, the included test file `example.mp4` is used (you don't need to add any arguments in this case).
+
+### Example usage:
+
+```bash
+anifetch video.mp4 -r 10 -W 40 -H 20 -c "--symbols wide --fg-only"
+```
+
+### Optional arguments:
+
+- `-f` / `--file`: path to the video file (the path can be added without the `-f` argument)
+- `-s` / `--sound`: optional sound file to play alongside (requires `ffplay`)
+- `-r` / `--framerate`: frame rate of playback
+- `-W` / `--width`: video width
+- `-H` / `--height`: video height (may be automatically fixed with the width)
+- `-c` / `--chafa`: extra arguments to pass to `chafa`
+- `-ff` / `--fast-fetch`: uses `fastfetch` instead of `neofetch` if available
+
+For full help:
+
+```bash
+anifetch --help
+```
+
+## 🎯 Creating a Shortcut (if installed manually)
+
+If you did not use `pipx` and installed manually via `git` (for developpers), you can still create an alias in your shell config (`~/.bashrc`, `~/.zshrc`, etc.):
+
+```bash
+alias anifetch='python3 /path/to/anifetch.py -f /path/to/video.mp4'
+```
+
+---
+
+## 📊 Benchmarks
 
 Here's the benchmark from running each cli 10 times. Tested on Linux Mint with Intel I5-12500H.
 
@@ -56,7 +130,7 @@ Here's the benchmark from running each cli 10 times. Tested on Linux Mint with I
 
 As it can be seen, **Anifetch** is quite fast if you cache the animations, especially when paired with fastfetch.
 
-## Notes
+## 📝 Notes
 
 Anifetch attempts to cache the animation so that it doesn't need to render them again when you run it with the same file. However, if the name of the file is the same, but it's contents has changed, it won't re-render it. In that case, you will need to add `--force-render` as an argument to `anifetch.py` so that it re-renders it. You only have to do this only once when you change the file contents.
 
@@ -68,7 +142,7 @@ If you set animation resolution really big it may not be able to keep up with th
 
 Currently only the `symbols` format of chafa is supported, formats like kitty, iterm etc. are not supported. If you try to tell chafa to use iterm, kitty etc. it will just override your format with `symbols` mode.
 
-## What's Next
+## 🚧 What's Next
 
 - [x] Add music support
 
@@ -106,6 +180,10 @@ Currently only the `symbols` format of chafa is supported, formats like kitty, i
 
 - [ ] Add an option to generate an mp4 with the terminal rendered animation(for putting it as a desktop background)
 
+## 💻 Dev commands
+
+Devs can use additional tools in the `tools` folder in order to test new features from Anifetch.
+
 ## Credits
 
 Neofetch: [Neofetch](https://github.com/dylanaraps/neofetch)