Metadata-Version: 2.5
Name: mycelium-client
Version: 0.4.1
Summary: The official client for the Mycelium file-sharing protocol.
Project-URL: Documentation, https://git.mojavesoft.org/mycelium/mycelium-client
Project-URL: Issues, https://git.mojavesoft.org/mycelium/mycelium-client/issues
Project-URL: Source, https://git.mojavesoft.org/mycelium/mycelium-client
Author-email: PPPDUD <mojavesoft@gmail.com>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
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 :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Requires-Dist: requests~=2.34
Provides-Extra: cli
Requires-Dist: click~=8.4; extra == 'cli'
Requires-Dist: tqdm~=4.67; extra == 'cli'
Description-Content-Type: text/markdown

# mycelium-client
This is the official reference implementation of the Mycelium client software, written in Python. It comes with a library for Python applications, as well as a CLI for end-users.

## Usage
> [!NOTE]
> The Mycelium client is currently under development, so this documentation may prove inaccurate for your release.
### As a CLI
In order to use the Mycelium client as a CLI, you need to install the `mycelium-client[cli]` variant:

~~~bash
pip3 install mycelium-client[cli]
~~~

Once that's done, you can get help information with `mycelium-client --help`:

~~~
$ mycelium-client --help
Usage: mycelium-client [OPTIONS] [COMMAND] [ARGS]...

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  fetch
  show
~~~

### As a Python library
The Mycelium client includes experimental support for use as a Python library without installing the CLI dependencies (this is what's supplied with the normal `mycelium-client` package):

~~~python3
import mycelium_client as mycelium
mycelium.fetch_hash(asset_hash="abcdef123...", oak="http://example.com:8000/", use_tqdm=False, quiet=True, timeout=15) # Fetch a hash.

mycelium.show_entries_md(filter_hash="", oak="http://example.com:8000/") # Generate human-readable Markdown describing the current entries advertised by an Oak. Leave filter_hash blank to disable hash filtering; set to a hash to filter for it.

mycelium.fetch_mycelium_file(content="CONTENTS-GO-HERE", quiet=True, use_tqdm=False, timeout=15) # Fetch using a Mycelium reference file. See example.mycelium for an example.
~~~

Make sure to use version pinning whenever you're writing code that depends on `mycelium-client`, as it has breaking changes frequently and is still very much not ready for production.

## Mycelium reference files
> [!NOTE]
> For security reasons, the Mycelium client CLI always saves files to the working directory when saving from an MRF fetch; this means that paths like ../output.txt and /tmp/output.txt will not work as intended.

The Mycelium client comes with built-in support for *Mycelium reference files* (MRFs for short). MRFs are brief files that give the client a list of suggested filenames, their hashes, the Oaks where they can be located, and a human-readable comment (optional). They're roughly equivalent to torrent files in BitTorrent.

Here's the example MRF file found at `example.mycelium`:
~~~
728ccb8dbeacf20d675bf3470481ef6432eb5d34f1da2aefe9e2dbf23abb6a7e:output1.png
00e991bfda1960f0f7b381a2b32f87c29f6204bd9791c76317b84be40ad9015f:output2.png
---
https://oak-f9d2f0e9.fastapicloud.dev/
---
This is an example Mycelium reference file (.mycelium). The first set of lines is a series of hashes followed by a colon and then their suggested file names.

The second set of lines provides suggested Oak servers that may have relevant listings, and the third set of lines is a human-readable comment.
~~~