Metadata-Version: 2.1
Name: infinite-craft
Version: 1.1.2
Summary: An API Wrapper of Neal's Infinite Craft game in Python for people to implement in their programs.
Author: sqdnoises
License: MIT License
        
        Copyright (c) 2024-present SqdNoises, Neal Agarwal
        
        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.
Project-URL: Homepage, https://github.com/sqdnoises/infinite-craft
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp
Requires-Dist: fastapi
Requires-Dist: uvicorn
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: bumpver; extra == "dev"
Requires-Dist: pip-tools; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# infinite-craft `1.1.2`
[![](https://img.shields.io/badge/infinite--craft_version-1.1.2-red)](https://github.com/sqdnoises/infinite-craft)
[![](https://img.shields.io/pypi/v/infinite-craft.svg)](https://pypi.org/project/infinite-craft/)
[![](https://img.shields.io/badge/License-MIT-red?labelColor=black)](LICENSE)
[![](https://img.shields.io/badge/Python_Version-3.10_|_3.11_|_3.12-blue)](https://python.org)
\
[![](https://github.com/sqdnoises/infinite-craft/actions/workflows/pytest.yml/badge.svg)](https://github.com/sqdnoises/infinite-craft/actions/workflows/pytest.yml)
[![](https://github.com/sqdnoises/infinite-craft/actions/workflows/publish-package-to-pypi.yml/badge.svg)](https://github.com/sqdnoises/infinite-craft/actions/workflows/publish-package-to-pypi.yml)
\
An API Wrapper of Neal's Infinite Craft game in Python for people to implement in their programs.

# Key Features:
- Stores elements in a neatly indented JSON file
- Starts with the four main elements: Water, Fire, Wind, Earth
- Uses [`neal.fun`](https://neal.fun/)'s [Infinite Craft](https://neal.fun/infinite-craft/) API to pair elements together
- Built-in ratelimiting handler
- Custom API support
- Asynchronous library
- Conveniently access discovered elements

# Table of Contents:
- **[Key Features](#key-features)**
- **[Installation](#installation)**
  - **[Dev requirements](#dev-requirements)**
  - **[In-dev installation](#in-dev-installation)**
- **[Usage Examples](#usage-examples)**
  - **[CLI](#cli)**
- **[How does it work?](#how-does-it-work)**
- **[To-do](#to-do)**
- **[Documentation](#documentation)**
- **[License](#license)**

# Installation
Requires **Python 3.10** or above.\
To install, run:
```
pip install infinite-craft
```

To update, run:
```
pip install -U infinite-craft
```

**NOTE:** If `pip` is not on PATH, you can use `python3 -m pip` (for Linux/MacOS) or `python -m pip` (for Windows) instead.

[**View `infinite-craft` on PyPI.**](https://pypi.org/project/infinite-craft/)

### Dev requirements
To install the dev requirements, either clone this repo and install requirements:
```
git clone https://github.com/sqdnoises/infinite-craft
pip install -r requirements.txt
```
or you can install the extra `dev`:
```
pip install infinite-craft[dev]
```
Recommended to use a virtual environment (`venv`) while using dev requirements.

### In-dev installation
If you want to use the in-dev version of this library, you can install it by doing (must have `git` installed):
```
pip install git+https://github.com/sqdnoises/infinite-craft.git
```

**Warning:** The library might be unstable especially if the build `Library Tests` is failing. Which you can see below.

[![](https://github.com/sqdnoises/infinite-craft/actions/workflows/pytest.yml/badge.svg)](https://github.com/sqdnoises/infinite-craft/actions/workflows/pytest.yml)

# Usage Examples
By using `async with`
```py
import asyncio
from infinitecraft import InfiniteCraft

async def main():
    async with InfiniteCraft() as game: # automatically start session and end session on async with end
        print(f"Pairing elements: {game.discoveries[0]} and {game.discoveries[1]}")
        result = await game.pair(game.discoveries[0], game.discoveries[1]) # Pair Water and Fire
        print(f"Result: {result}")

asyncio.run(main())
```

Another `async with` example with manual session control
```py
import asyncio
from infinitecraft import InfiniteCraft

game = InfiniteCraft(manual_control=True) # control start and stop of session automatically

async def main():
    await game.start() # Start InfiniteCraft Session
    
    async with game:
        print(f"Pairing elements: {game.discoveries[0]} and {game.discoveries[1]}")
        result = await game.pair(game.discoveries[0], game.discoveries[1]) # Pair Water and Fire
        print(f"Result: {result}")

    await game.close() # Close InfiniteCraft Session

asyncio.run(main())
```

Example that is basically like manual control except we don't need to use `async with`
```py
import asyncio
from infinitecraft import InfiniteCraft

game = InfiniteCraft()

async def main():
    await game.start() # Start InfiniteCraft Session
    
    print(f"Pairing elements: {game.discoveries[0]} and {game.discoveries[1]}")
    result = await game.pair(game.discoveries[0], game.discoveries[1]) # Pair Water and Fire
    print(f"Result: {result}")

    await game.close() # Close InfiniteCraft Session

asyncio.run(main())
```

Example that pings the API to check its latency
```py
import asyncio
from infinitecraft import InfiniteCraft

async def main():
    async with InfiniteCraft() as game:
        ping = await game.ping() # return type: `float` in seconds
        print(f"Ping: {round(ping * 1000)} ms") # turn into milliseconds and round

asyncio.run(main())
```

Example that pairs two user-defined elements and doesn't store the result in `game.discoveries`
```py
import asyncio
from infinitecraft import InfiniteCraft, Element

async def main():
    async with InfiniteCraft() as game:
        first = Element("Shawarma") # Emoji is not fetched, you must specify it with emoji=""
        second = Element("Chicken")
        
        print(f"Pairing elements: {first} and {second}")
        result = await game.pair(first, second) # Pair Shawarma and Chicken
        print(f"Result: {result}")

asyncio.run(main())
```

## CLI
By default, two CLI apps are also installed. `infinite-craft` and `infinitecraft`.\
You can use either, both do the exact same thing.

Display help:
```
infinite-craft -h
```

Reset your discoveries JSON file to the initial 4 elements
```
infinite-craft reset -d "/path/to/discoveries.json"
```

**NOTE:** If `infinite-craft` or `infinitecraft` are not on PATH, you can use `python3 -m infinite-craft` or `python3 -m infinitecraft` (Linux/MacOS) or `python3 -m infinite-craft` or `python3 -m infinitecraft` (Windows) instead.

# How does it work?
This library basically contacts the URL: https://neal.fun/api/infinite-craft/pair?first=element+name&second=element+name \
tricks it with some headers, and handles everything accordingly. Everything is handled in a user-friendly manner and asynchronously, so it should be really easy to use it in your programs.

# To-do
- [x] Release version 1.0.0 on PyPI
- [ ] Make a discord server for support
- [x] Add a runnable and configurable CLI mock API server
- [ ] Make docs
- [ ] Make a playable Infinite Craft CLI game (interactive, probably)

# Documentation
Documentation coming soon
However everything is documented well in the code with docstrings.

<div align="center">

# License
[![](https://img.shields.io/badge/LICENSE-MIT-red?style=for-the-badge&labelColor=black)](LICENSE)\
View the **[MIT License](LICENSE)** license that comes with this library.

</div>

---

<div align="center">

### 🌟 Please star the repo and show some love 💖

</div>
