Metadata-Version: 2.1
Name: osrsbox
Version: 1.2.1
Summary: A complete and up-to-date database of Old School Runescape (OSRS) items accessible using a Python API.
Home-page: https://github.com/osrsbox/osrsbox-db
Author: PH01L
Author-email: phoil@osrsbox.com
License: GPLv3
Description: 
        # osrsbox
        
        ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/osrsbox.svg) [![PyPI version](https://badge.fury.io/py/osrsbox.svg)](https://badge.fury.io/py/osrsbox) ![PyPI - Downloads](https://img.shields.io/pypi/dm/osrsbox.svg)
        
        ## A complete and up-to-date database of Old School Runescape (OSRS) items accessible using a Python API
        
        The `osrsbox` package is a complete and up-to-date database of OSRS items that is accessible via a Python API. **Complete** means it holds every single item in OSRS. **Up-to-date** means this database is updated after every weekly game update to ensure accurate information. This package contains just the Python API and the actual item database - the tools and data used to build the item database are available from the [`osrsbox-db` GitHub repository](https://github.com/osrsbox/osrsbox-db).
        
        ## Table of Contents
        
        - [Quick Start](#quick-start)
        - [OSRS Items API](#osrs-items-api)
        - [Changelog](#changelog)
        
        # Quick Start
        
        - Make sure you have >= Python 3.6
        - Install package using: `pip install osrsbox`
        - Import items API using: `from osrsbox import items_api`
        - Load all items using: `all_db_items = items_api.load()`
        - Loop items using: `for item in all_db_items: print(item.name)`
        
        ### Package Requirements
        
        - Python 3.6 or above
        - Dataclasses package (if Python is below 3.7)
        
        ### Installation
        
        The easiest way to install the osrsbox package is through the [Python Package Index](http://pypi.python.org/) using the `pip` command. You need to have `pip` installed - and make sure it is updated (especially on Windows). Then you can install the `osrsbox` package using the following `pip` command:
        
        ```
        pip install osrsbox
        ```
        
        This package is consistently updated - usually after each weekly in-game update. This is because the in-game update usually introduces additional items into the game or changes existing items. Therefore, you should regularly check and update the `osrsbox` package. To achieve this, run `pip` with the `upgrade` flag.
        
        ```
        pip install --upgrade osrsbox
        ```
        
        ### Usage 
        
        The key use of the `osrsbox` package is to load and automate the processing of OSRS items and their associated metadata. 
        
        You can load the package using `import osrsbox`, however, you probably want to load the `items_api` module. A simple example of using the package to `load` all the items, then loop and print out the item ID and name of every item in OSRS is provided below:
        
        ```
        >>> from osrsbox import items_api
        >>> all_db_items = items_api.load()
        >>> for item in all_db_items:
        ...     print(item.id, item.name)
        ```
        
        # OSRS Items API
        
        Each item is represented by Python objects, specifically using Python dataclasses. There are three types of objects that can be used to represent part of an in-game OSRS item, each outlined in the following subsections.
        
        ### Item Definition
        
        An `ItemDefinition` object type includes basic item metadata such as `id`, `name`, `examine` text, store `cost`, `high_alch` and `low_alch` values and `quest_item` association. Every item object in the item database. All of the properties available are listed in the table below including the property name, the data types used, a description of the property and if the property is required to be populated - if not required, the property value can potentially be set to `None`.
        
        | Property | Data type | Description | Required |
        | -------- | --------- | ----------- | -------- |
        | id | integer | Unique OSRS item ID number. | Yes |
        | name | string | Name of the item. | Yes |
        | members | boolean | If the item is a members-only. | Yes |
        | tradeable | boolean | If the item is tradeable (between players and on the GE). | Yes |
        | tradeable_on_ge | boolean | If the item is tradeable (only on GE). | Yes |
        | stackable | boolean | If the item is stackable (in inventory). | Yes |
        | noted | boolean | If the item is noted. | Yes |
        | noteable | boolean | If the item is noteable. | Yes |
        | linked_id_item | integer | The linked ID of the actual item (if noted/placeholder). | No |
        | linked_id_noted | integer | The linked ID of an item in noted form. | No |
        | linked_id_placeholder | integer | The linked ID of an item in placeholder form. | No |
        | placeholder | boolean | If the item is a placeholder. | Yes |
        | equipable | boolean | If the item is equipable (based on right-click menu entry). | Yes |
        | equipable_by_player | boolean | If the item is equipable by a player and is equipable in-game. | Yes |
        | cost | integer | The store price of an item. | Yes |
        | lowalch | integer | The low alchemy value of the item (cost * .4). | Yes |
        | highalch | integer | The high alchemy value of the item (cost * .6). | Yes |
        | weight | number | The weight (in kilograms) of the item. | No |
        | buy_limit | integer | The GE buy limit of the item. | No |
        | quest_item | boolean | If the item is associated with a quest. | Yes |
        | release_date | string | Date the item was released (in ISO8601 format). | No |
        | duplicate | boolean | If the item is a duplicate. | Yes |
        | examine | string | The examine text for the item. | No |
        | wiki_name | string | The OSRS Wiki name for the item. | No |
        | wiki_url | string | The OSRS Wiki URL (possibly including anchor link). | No |
        | equipment | object | The equipment bonuses of equipable armor/weapons. | No |
        | weapon | object | The information about weapon properties. | No |
        
        ### Item Equipment
        
        Many items in OSRS are equipable, this includes armor, weapons, and other _wearable_ items. Any equipable item has additional properties stored as an `ItemEquipment` object including attributes such as `attack_slash`, `defence_crush` and `melee_strength` values. The `ItemEquipment` object is nested within an `ItemDefinition` under the `equipment` key. It is very important to note that not all items in OSRS are equipable. Only items with the `equipable_by_player` property set to `true` are equipable. The `equipable` property is similar, but this is the raw data extracted from the game cache - and can sometimes be incorrect (not equipable by a player). All of the properties available for equipable items are listed in the table below including the property name, the data types used, a description of the property and if the property is required to be populated - if not required, the property value can potentially be set to `None`. 
        
        | Property | Data type | Description | Required |
        | -------- | --------- | ----------- | -------- |
        | attack_stab | integer | The attack stab bonus of the item. | Yes |
        | attack_slash | integer | The attack slash bonus of the item. | Yes |
        | attack_crush | integer | The attack crush bonus of the item. | Yes |
        | attack_magic | integer | The attack magic bonus of the item. | Yes |
        | attack_ranged | integer | The attack ranged bonus of the item. | Yes |
        | defence_stab | integer | The defence stab bonus of the item. | Yes |
        | defence_slash | integer | The defence slash bonus of the item. | Yes |
        | defence_crush | integer | The defence crush bonus of the item. | Yes |
        | defence_magic | integer | The defence magic bonus of the item. | Yes |
        | defence_ranged | integer | The defence ranged bonus of the item. | Yes |
        | melee_strength | integer | The melee strength bonus of the item. | Yes |
        | ranged_strength | integer | The ranged strength bonus of the item. | Yes |
        | magic_damage | integer | The magic damage bonus of the item. | Yes |
        | prayer | integer | The prayer bonus of the item. | Yes |
        | slot | string | The equipment slot associated with the item (e.g., head). | Yes |
        | requirements | object, null | An object of requirements {skill: level}. | Yes |
        
        ### Item Weapon
        
        A select number of items in OSRS are equipable weapons. Any equipable item that is a weapon has additional properties stored as an `ItemWeapon` object including attributes such as `attack_speed` and `weapon_types` values. The `ItemWeapon` object is nested within an `ItemDefinition` under the `weapon` key. Additionally, each weapon has an array of combat stances associated with it to determine the `combat_style`, `attack_type`, `attack_style` and any `bonuses` or combat `experience` association. It is very important to note that not all items in OSRS are equipable weapons. Only items with the `equipable_weapon` property set to `true` are equipable. All of the properties available for equipable weapons are listed in the table below including the property name, the data types used, a description of the property and if the property is required to be populated - if not required, the property value can potentially be set to `None`
        
        | Property | Data type | Description | Required |
        | -------- | --------- | ----------- | -------- |
        | attack_speed | integer | The attack speed of a weapon. | Yes |
        | weapon_type | string | The weapon classification (e.g., axe) | Yes |
        | stances | array | An array of weapon stance information | Yes |
        
        # Changelog
        
        - `1.2.1`: Added monster database (beta).
        - `1.1.26`: Release for game update: 2019/08/22.
        - `1.1.25`: Updated project documentation.
        - `1.1.24`: Updated JSON schema and added duplicate item property.
        - `1.1.23`: Release for game update: 2019/08/15.
        - `1.1.22`: Release for game update: 2019/08/08.
        - `1.1.21`: Release for game update: 2019/07/25 and 2019/08/01 (SOTE).
        - `1.1.20`: Improved item data accuracy. Added wiki_name property and wiki_url anchor.
        - `1.1.19`: Release for game update: 2019/07/18.
        - `1.1.18`: Fixed stackable property. Added improved item ID linking.
        - `1.1.17`: Release for game update: 2019/07/11.
        - `1.1.16`: Converted all `release_date` values to ISO8601 format.
        - `1.1.15`: Release for game update: 2019/07/04.
        - `1.1.14`: Release for game update: 2019/06/27.
        - `1.1.13`: Release for game update: 2019/06/20.
        - `1.1.12`: Release for game update: 2019/05/30.
        - `1.1.11`: Release for game update 2019/06/06.
        - `1.1.10`: Release for game update 2019/05/23.
        - `1.1.9`: Release for game update 2019/05/16.
        - `1.1.8`: Release for week 2019/05/09 (no actual game update).
        - `1.1.7`: Release for game update 2019/05/02.
        - `1.1.6`: Release for game update 2019/04/25, added ItemWeapon class.
        - `1.1.5`: Release for game update 2019/04/18.
        - `1.1.4`: Update for changes to new treasure trail items.
        - `1.1.3`: Release for game update 2019/04/11.
        - `1.1.2`: Converted ItemDefinition, ItemEquipment to dataclass.
        - `1.1.1`: Release for game update 2019/04/04.
        - `1.1.0`: Changed equipable item requirements to an object.
        - `1.0.9`: Release for game update 2019/03/28.
        - `1.0.8`: Fixed packaging issue.
        - `1.0.7`: Updated project documentation.
        - `1.0.6`: Fixed package install bug.
        - `1.0.5`: Release for game update 2019/03/21.
        - `1.0.4`: Configured Travis CI for automated deployment.
        - `1.0.3`: Release for game update 2019/03/14.
        - `1.0.2`: Release for game update 2019/03/07.
        - `1.0.1`: Release for game update 2019/02/14.
        - `1.0.0`: Initial release.
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=3.6.0
Description-Content-Type: text/markdown
