bandcampsync-tui 0.7.0__tar.gz

bandcampsync_tui-0.7.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, meeb <meeb@meeb.org>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

bandcampsync_tui-0.7.0/MANIFEST.in

@@ -0,0 +1 @@
+include *.txt

bandcampsync_tui-0.7.0/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: bandcampsync-tui
+Version: 0.7.0
+Summary: A Python module and script to synchronise media purchased on bandcamp.com with a local directory. Fork of meeb/bandcampsync with Rich TUI and cross-platform improvements.
+Home-page: https://codeberg.org/imigueldiaz/bandcampsync-tui
+Author: Ignacio de Miguel Díaz
+Author-email: imigueldiaz@tutamail.com
+License: BSD-3-Clause
+Project-URL: Homepage, https://codeberg.org/imigueldiaz/bandcampsync-tui
+Project-URL: Bug Tracker, https://codeberg.org/imigueldiaz/bandcampsync-tui/issues
+Project-URL: Source, https://codeberg.org/imigueldiaz/bandcampsync-tui
+Project-URL: Changelog, https://codeberg.org/imigueldiaz/bandcampsync-tui/src/branch/main/CHANGELOG.md
+Keywords: bandcampsync,bandcamp,media,sync,tui,download,music
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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: Environment :: Console
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: curl_cffi
+Requires-Dist: beautifulsoup4
+Requires-Dist: html5lib
+Requires-Dist: rich
+Requires-Dist: setuptools
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# BandcampSync-TUI
+
+[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI](https://img.shields.io/badge/PyPI-0.7.0-blue?logo=pypi&logoColor=white)](https://pypi.org/project/bandcampsync-tui/)
+[![License](https://img.shields.io/badge/License-BSD--3--Clause-green)](LICENSE)
+[![PSF Member](https://img.shields.io/badge/PSF-Supporting%20Member-FFD43B?logo=python&logoColor=blue)](https://www.python.org/psf/membership/)
+
+> **🍴 Fork Notice**: This is a fork of
+> [meeb/bandcampsync](https://github.com/meeb/bandcampsync) by
+> [@meeb](https://github.com/meeb). The original project provided the foundation
+> for this work. This fork extends it with a modern TUI, improved cross-platform
+> support, and enhanced download capabilities. See
+> [What's Different in This Fork](#-whats-different-in-this-fork) for details.
+
+---
+
+**BandcampSync-TUI** is a Python module and command line script which
+synchronises media purchased on a Bandcamp (<https://bandcamp.com/>) account
+with a local directory.
+
+You may use this to download media you have purchased from Bandcamp to a local
+media server, such as Plex or Jellyfin.
+
+Most media items purchased on Bandcamp have high quality download options
+available and BandcampSync-TUI defaults to `flac`.
+
+![BandcampSync TUI](docs/tui-preview.png)
+
+## ✨ What's Different in This Fork
+
+This fork introduces several significant improvements over the original:
+
+| Feature             | Original          | This Fork                                         |
+| ------------------- | ----------------- | ------------------------------------------------- |
+| **Package Name**    | `bandcampsync`    | `bandcampsync-tui`                                |
+| **User Interface**  | Plain text output | Rich TUI with progress bars, spinners, and colors |
+| **Download Speed**  | Single-stream     | Multi-part parallel downloads (4 threads)         |
+| **Windows Support** | Basic             | Full cross-platform with proper path sanitization |
+| **HTTP Client**     | `requests`        | `curl_cffi` (better anti-bot handling)            |
+| **Ethics**          | —                 | [ETHICAL.md](ETHICAL.md) statement included       |
+
+### Key Improvements
+
+- 🎨 **Beautiful TUI**: Progress bars with download speed/ETA, color-coded
+  messages, spinner animations
+- 🏷️ **Download ID Visibility**: The TUI now displays the download item ID (e.g. `[ID 123456]`) in progress descriptions and status messages to make it easy to add items to the ignore file.
+- ⚡ **Faster Downloads**: Large files (>5MB) download in parallel chunks
+- 🖥️ **True Cross-Platform**: Handles Windows-forbidden characters, reserved
+  names, and temp file cleanup
+- 🛡️ **Better Reliability**: Automatic retry with exponential backoff, graceful
+  error handling
+- 📜 **Ethical Commitment**: See our [Ethical Statement](ETHICAL.md) for project
+  values
+
+For a complete list of changes, see the [CHANGELOG](CHANGELOG.md).
+
+---
+
+## How It Works
+
+When called, `bandcampsync-tui` will:
+
+1. Authenticate to bandcamp.com as you using your exported session cookies
+2. Scan your local media directory for existing downloaded items
+3. Index a list of all of your purchased items in your Bandcamp collection
+4. Download the archive of missing items not downloaded already from your
+   collection
+5. Unzip the archive and move the contents to the local media directory
+
+The media directory will have the following format:
+
+## Docker
+
+This fork does not provide or maintain a Docker image. If you need a
+containerised setup, please use the original project's Docker resources:
+
+- Original project: <https://github.com/meeb/bandcampsync>
+- Official image: ghcr.io/meeb/bandcampsync:latest
+
+We recommend using the upstream project's image and examples for container
+deployments, as they maintain the Docker artifacts and runbook. This repository
+focuses on the interactive TUI and local improvements.
+
+If you'd like, I can add a short compatibility note or a simple example showing
+how to adapt the upstream Dockerfile for this fork — tell me and I'll draft it.
+
+## Configuration
+
+BandcampSync-TUI requires minimal configuration. First, it requires your session
+cookies from an authenticated Bandcamp account. The easiest way to get this is
+to go to <https://bandcamp.com/> in your browser and log in with your account.
+
+Next, open the developer tools in your browser (F12 button on most browsers, or
+select "developer tools" from the options menu).
+
+Reload the index page and find the index page request in your network requests
+tab of your browser. Go to the "Request Headers" section then select and copy
+the string after the `Cookie` header. The string should look something like
+this:
+
+```text
+client_id=00B1F3C8EB48E181A185CCD041E40C0E8F; session=1%0893C88%570EE405455%%8DEC37B5BC393983DB983DD%%BDFD46C3B8A0%%580DA466D5CD; identity=1%HhehuehUFEUiuebn%%2ADB72300DAE573%BEEF389A1B526EA35AC38019FA0A6F%11B4BD5FBC18B83F720; js_logged_in=1; logout=%7B%22username%22%3A%22someuser%22%7D; download_encoding=401; BACKENDID3=some-sever-name
+```
+
+Save this string to a file called `cookies.txt`.
+
+![Getting your session cookies](https://github.com/meeb/bandcampsync/blob/main/docs/cookies.jpg?raw=true)
+
+You need to save your session ID from cookies manually because Bandcamp has a
+captcha on the login form so BandcampSync-TUI can't log in with your username
+and password for you.
+
+IMPORTANT NOTE: Keep the `cookies.txt` file safe! Anyone with access to this
+file can log into your Bandcamp account, impersonate you, potentially make
+purchases and generally have total access to your Bandcamp account!
+
+You can also use Netscape formatted cookie export files if you have exported
+your cookies using a cookie exporter plugin or similar tool.
+
+## CLI usage
+
+Once you have the Python `bandcampsync-tui` module installed you can call it
+with the `bandcampsync-tui` command:
+
+```bash
+bandcampsync-tui --cookies cookies.txt --directory /path/to/music
+```
+
+or in shorthand:
+
+```bash
+bandcampsync-tui -c cookies.txt -d /path/to/music
+```
+
+You can use `-t` or `--temp-dir` to set the temporary download directory used.
+You can use `-i` or `--ignore` to bypass artists that have data issues that your
+OS can not handle.
+
+See `-h` or `--help` for the full list of command line options.
+
+```bash
+bandcampsync-tui --cookies cookies.txt --directory /path/to/music --ignore "badband"
+```
+
+`--ignore` supports multiple strings space separated strings, for example
+`--ignore "band1 band2 band3"`.
+
+You can use `-I` or `--ignore-file` to specify the path to a file containing
+bandcamp ids of each item to skip.
+
+```text
+1546934218  # Chrome Sparks / Sparks EP
+1418240212  # Chrome Sparks / Goddess EP
+```
+
+If you do, the items downloaded will be appended to the file, so that the next
+time you run the script those items will not be re-downloaded. This means you
+can use media managers such as Lidarr to rename artist, album and track names
+automatically, rename the directory, or even move the items out of the download
+directory without issues.
+
+You can notify an external HTTP server when new items have been loaded with `-n`
+or `--notify-url`.
+
+```bash
+bandcampsync ... --notify-url "http://some.service.local/some-uri"
+```
+
+You can use this to call a "refresh" hook on media servers (for example rescan a
+Plex or Jellyfin library). The `--notify-url` parameter, if set, simply makes an
+HTTP GET request to the specified URL and confirms it returns a `2XX` response.
+
+For advanced notify URLs you can use the following `--notify-url` format:
+
+`method url headers body`
+
+`method` must be one of `GET` or `POST`. `url` is any URL. `headers` are a comma
+separated list of `key=value` pairs and `body` is an body string to send if the
+`method` is `POST`. You can use `-` for header and body values to leave them
+unset. Some examples:
+
+`GET http://some.service.local/some-uri - -`
+
+`GET http://some.service.local/some-uri header1=abc,header2 -`
+
+`POST http://some.service.local/some-uri auth-header=abc somedata`
+
+## Formats
+
+By default, BandcampSync will download your music in the `flac` format. You can
+specify another format with the `--format` argument. Common Bandcamp download
+formats are:
+
+| Name            | Description                                                     |
+| --------------- | --------------------------------------------------------------- |
+| `mp3-v0`        | Variable bitrate MP3. Small file sizes. OK quality.             |
+| `mp3-320`       | High quality MP3. Medium file sizes. Good quality.              |
+| `flac`          | Lossless audio. Large file sizes. Original Quality.             |
+| `aac-hi`        | Apple variable bitrate format. Small file sizes. OK quality.    |
+| `aiff-lossless` | Uncompressed audio format. Biggest file size. Original quality. |
+| `vorbis`        | Open source lossy format. Small file sizes. OK quality.         |
+| `alac`          | Apple lossless format. Large file sizes. Original quality.      |
+| `wav`           | Uncompressed audio format. Biggest file size. Original quality. |
+
+## Contributing
+
+All properly formatted and sensible pull requests, issues and comments are
+welcome.
+
+## Acknowledgments
+
+This project is a fork of
+**[meeb/bandcampsync](https://github.com/meeb/bandcampsync)** created by
+[@meeb](https://github.com/meeb).
+
+Thank you to the original author and all contributors for building the
+foundation that made this fork possible.
+
+## License
+
+This project is licensed under the BSD 3-Clause License - see the
+[LICENSE](LICENSE) file for details.
+
+The original project by [@meeb](https://github.com/meeb) is also licensed under
+the BSD 3-Clause License.
+
+## Ethical Commitment
+
+This project includes an [Ethical Statement](ETHICAL.md) that outlines our
+values and principles regarding the responsible use of this software. We
+encourage all users to read and consider these principles when using, modifying,
+or distributing this software.

bandcampsync_tui-0.7.0/README.md

@@ -0,0 +1,232 @@
+# BandcampSync-TUI
+
+[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI](https://img.shields.io/badge/PyPI-0.7.0-blue?logo=pypi&logoColor=white)](https://pypi.org/project/bandcampsync-tui/)
+[![License](https://img.shields.io/badge/License-BSD--3--Clause-green)](LICENSE)
+[![PSF Member](https://img.shields.io/badge/PSF-Supporting%20Member-FFD43B?logo=python&logoColor=blue)](https://www.python.org/psf/membership/)
+
+> **🍴 Fork Notice**: This is a fork of
+> [meeb/bandcampsync](https://github.com/meeb/bandcampsync) by
+> [@meeb](https://github.com/meeb). The original project provided the foundation
+> for this work. This fork extends it with a modern TUI, improved cross-platform
+> support, and enhanced download capabilities. See
+> [What's Different in This Fork](#-whats-different-in-this-fork) for details.
+
+---
+
+**BandcampSync-TUI** is a Python module and command line script which
+synchronises media purchased on a Bandcamp (<https://bandcamp.com/>) account
+with a local directory.
+
+You may use this to download media you have purchased from Bandcamp to a local
+media server, such as Plex or Jellyfin.
+
+Most media items purchased on Bandcamp have high quality download options
+available and BandcampSync-TUI defaults to `flac`.
+
+![BandcampSync TUI](docs/tui-preview.png)
+
+## ✨ What's Different in This Fork
+
+This fork introduces several significant improvements over the original:
+
+| Feature             | Original          | This Fork                                         |
+| ------------------- | ----------------- | ------------------------------------------------- |
+| **Package Name**    | `bandcampsync`    | `bandcampsync-tui`                                |
+| **User Interface**  | Plain text output | Rich TUI with progress bars, spinners, and colors |
+| **Download Speed**  | Single-stream     | Multi-part parallel downloads (4 threads)         |
+| **Windows Support** | Basic             | Full cross-platform with proper path sanitization |
+| **HTTP Client**     | `requests`        | `curl_cffi` (better anti-bot handling)            |
+| **Ethics**          | —                 | [ETHICAL.md](ETHICAL.md) statement included       |
+
+### Key Improvements
+
+- 🎨 **Beautiful TUI**: Progress bars with download speed/ETA, color-coded
+  messages, spinner animations
+- 🏷️ **Download ID Visibility**: The TUI now displays the download item ID (e.g. `[ID 123456]`) in progress descriptions and status messages to make it easy to add items to the ignore file.
+- ⚡ **Faster Downloads**: Large files (>5MB) download in parallel chunks
+- 🖥️ **True Cross-Platform**: Handles Windows-forbidden characters, reserved
+  names, and temp file cleanup
+- 🛡️ **Better Reliability**: Automatic retry with exponential backoff, graceful
+  error handling
+- 📜 **Ethical Commitment**: See our [Ethical Statement](ETHICAL.md) for project
+  values
+
+For a complete list of changes, see the [CHANGELOG](CHANGELOG.md).
+
+---
+
+## How It Works
+
+When called, `bandcampsync-tui` will:
+
+1. Authenticate to bandcamp.com as you using your exported session cookies
+2. Scan your local media directory for existing downloaded items
+3. Index a list of all of your purchased items in your Bandcamp collection
+4. Download the archive of missing items not downloaded already from your
+   collection
+5. Unzip the archive and move the contents to the local media directory
+
+The media directory will have the following format:
+
+## Docker
+
+This fork does not provide or maintain a Docker image. If you need a
+containerised setup, please use the original project's Docker resources:
+
+- Original project: <https://github.com/meeb/bandcampsync>
+- Official image: ghcr.io/meeb/bandcampsync:latest
+
+We recommend using the upstream project's image and examples for container
+deployments, as they maintain the Docker artifacts and runbook. This repository
+focuses on the interactive TUI and local improvements.
+
+If you'd like, I can add a short compatibility note or a simple example showing
+how to adapt the upstream Dockerfile for this fork — tell me and I'll draft it.
+
+## Configuration
+
+BandcampSync-TUI requires minimal configuration. First, it requires your session
+cookies from an authenticated Bandcamp account. The easiest way to get this is
+to go to <https://bandcamp.com/> in your browser and log in with your account.
+
+Next, open the developer tools in your browser (F12 button on most browsers, or
+select "developer tools" from the options menu).
+
+Reload the index page and find the index page request in your network requests
+tab of your browser. Go to the "Request Headers" section then select and copy
+the string after the `Cookie` header. The string should look something like
+this:
+
+```text
+client_id=00B1F3C8EB48E181A185CCD041E40C0E8F; session=1%0893C88%570EE405455%%8DEC37B5BC393983DB983DD%%BDFD46C3B8A0%%580DA466D5CD; identity=1%HhehuehUFEUiuebn%%2ADB72300DAE573%BEEF389A1B526EA35AC38019FA0A6F%11B4BD5FBC18B83F720; js_logged_in=1; logout=%7B%22username%22%3A%22someuser%22%7D; download_encoding=401; BACKENDID3=some-sever-name
+```
+
+Save this string to a file called `cookies.txt`.
+
+![Getting your session cookies](https://github.com/meeb/bandcampsync/blob/main/docs/cookies.jpg?raw=true)
+
+You need to save your session ID from cookies manually because Bandcamp has a
+captcha on the login form so BandcampSync-TUI can't log in with your username
+and password for you.
+
+IMPORTANT NOTE: Keep the `cookies.txt` file safe! Anyone with access to this
+file can log into your Bandcamp account, impersonate you, potentially make
+purchases and generally have total access to your Bandcamp account!
+
+You can also use Netscape formatted cookie export files if you have exported
+your cookies using a cookie exporter plugin or similar tool.
+
+## CLI usage
+
+Once you have the Python `bandcampsync-tui` module installed you can call it
+with the `bandcampsync-tui` command:
+
+```bash
+bandcampsync-tui --cookies cookies.txt --directory /path/to/music
+```
+
+or in shorthand:
+
+```bash
+bandcampsync-tui -c cookies.txt -d /path/to/music
+```
+
+You can use `-t` or `--temp-dir` to set the temporary download directory used.
+You can use `-i` or `--ignore` to bypass artists that have data issues that your
+OS can not handle.
+
+See `-h` or `--help` for the full list of command line options.
+
+```bash
+bandcampsync-tui --cookies cookies.txt --directory /path/to/music --ignore "badband"
+```
+
+`--ignore` supports multiple strings space separated strings, for example
+`--ignore "band1 band2 band3"`.
+
+You can use `-I` or `--ignore-file` to specify the path to a file containing
+bandcamp ids of each item to skip.
+
+```text
+1546934218  # Chrome Sparks / Sparks EP
+1418240212  # Chrome Sparks / Goddess EP
+```
+
+If you do, the items downloaded will be appended to the file, so that the next
+time you run the script those items will not be re-downloaded. This means you
+can use media managers such as Lidarr to rename artist, album and track names
+automatically, rename the directory, or even move the items out of the download
+directory without issues.
+
+You can notify an external HTTP server when new items have been loaded with `-n`
+or `--notify-url`.
+
+```bash
+bandcampsync ... --notify-url "http://some.service.local/some-uri"
+```
+
+You can use this to call a "refresh" hook on media servers (for example rescan a
+Plex or Jellyfin library). The `--notify-url` parameter, if set, simply makes an
+HTTP GET request to the specified URL and confirms it returns a `2XX` response.
+
+For advanced notify URLs you can use the following `--notify-url` format:
+
+`method url headers body`
+
+`method` must be one of `GET` or `POST`. `url` is any URL. `headers` are a comma
+separated list of `key=value` pairs and `body` is an body string to send if the
+`method` is `POST`. You can use `-` for header and body values to leave them
+unset. Some examples:
+
+`GET http://some.service.local/some-uri - -`
+
+`GET http://some.service.local/some-uri header1=abc,header2 -`
+
+`POST http://some.service.local/some-uri auth-header=abc somedata`
+
+## Formats
+
+By default, BandcampSync will download your music in the `flac` format. You can
+specify another format with the `--format` argument. Common Bandcamp download
+formats are:
+
+| Name            | Description                                                     |
+| --------------- | --------------------------------------------------------------- |
+| `mp3-v0`        | Variable bitrate MP3. Small file sizes. OK quality.             |
+| `mp3-320`       | High quality MP3. Medium file sizes. Good quality.              |
+| `flac`          | Lossless audio. Large file sizes. Original Quality.             |
+| `aac-hi`        | Apple variable bitrate format. Small file sizes. OK quality.    |
+| `aiff-lossless` | Uncompressed audio format. Biggest file size. Original quality. |
+| `vorbis`        | Open source lossy format. Small file sizes. OK quality.         |
+| `alac`          | Apple lossless format. Large file sizes. Original quality.      |
+| `wav`           | Uncompressed audio format. Biggest file size. Original quality. |
+
+## Contributing
+
+All properly formatted and sensible pull requests, issues and comments are
+welcome.
+
+## Acknowledgments
+
+This project is a fork of
+**[meeb/bandcampsync](https://github.com/meeb/bandcampsync)** created by
+[@meeb](https://github.com/meeb).
+
+Thank you to the original author and all contributors for building the
+foundation that made this fork possible.
+
+## License
+
+This project is licensed under the BSD 3-Clause License - see the
+[LICENSE](LICENSE) file for details.
+
+The original project by [@meeb](https://github.com/meeb) is also licensed under
+the BSD 3-Clause License.
+
+## Ethical Commitment
+
+This project includes an [Ethical Statement](ETHICAL.md) that outlines our
+values and principles regarding the responsible use of this software. We
+encourage all users to read and consider these principles when using, modifying,
+or distributing this software.