>Illviljan |
>OmegaK2 |
| Line 7: |
Line 7: |
| ==Overview== | | ==Overview== |
|
| |
|
| ===Goals of the Project===
| | PyPoE can be downloaded from [https://github.com/OmegaK2/PyPoE github]. Follow the instructions to install it. |
|
| |
|
| * provide a mostly complete and stable python3 api to work with Path of Exile and it's files
| | More detailed instructions can be found in the documentation; a live version of the documentation resides [http://omegak2.net/poe/PyPoE/ here]. |
| * have a stable and useful UI binding to browse the files
| |
| * provide CLI tools for extracting files for convince
| |
| * provide utilities to publish the data on the Path of Exile wiki
| |
|
| |
|
| ===Features=== | | ==Usage on the wiki== |
| * Development Library
| |
| * Graphical User Interface (UI or GUI)
| |
| * Command Line Interface (CLI)
| |
|
| |
|
| ==Installation==
| | PyPoE is used on the wiki to help with exporting game data to the wiki to reduce the manual work load from editors. |
|
| |
|
| These installation instructions are currently aimed at development builds.
| | There are generally no restrictions placed on who can use PyPoE, but please note that without bot or admin access regular users are subjects to some limits in regards to automated usage. It is possible however to simply write something to your local disk (using the --write option) and then manually apply it to the wiki. |
|
| |
|
| ===Prerequisites===
| | The process of uploading images is generally manual; for PyPoE to be able to export uncompressed images see the [[Path_of_Exile_Wiki:Community_portal#Uncompressed_DDS_files_from_the_ggpk_for_the_wiki instructions on the community portal]]. |
|
| |
|
| ====Python 3.4==== | | ===What is PyPoE currently responsible for?=== |
|
| |
|
| Windows:
| |
| * Navigate to https://www.python.org/downloads/ and download the latest version of python 3.4
| |
| * Install and follow the instructions on screen
| |
| * In particular make sure the Python executable as well as the scripts folder are located in the %PATH% variable
| |
|
| |
| Linux:
| |
| * Ubuntu/Debian: apt-get install python3
| |
|
| |
| ====Git====
| |
|
| |
| Windows:
| |
| * Navigate to https://git-scm.com/ and download the latest version of git
| |
| * Make sure git is added to the %PATH% variable on windows
| |
|
| |
| Linux:
| |
| * Ubuntu/Debian: apt-get install pip
| |
|
| |
| ====QT4 (UI only, Linux only)====
| |
|
| |
| See http://pyside.readthedocs.org/en/latest/building/linux.html for details.
| |
|
| |
|
| |
| ===Installing PyPoE===
| |
|
| |
| It is highly recommended to use the development build if no stable release is available, so updates from git apply to the install.
| |
|
| |
| Linux:
| |
| * On many distributions, python and pip can link to either version 2 or version 3 depending on the system defaults, instead consider using
| |
| ** <code>python3</code> instead of <code>python</code>
| |
| ** <code>pip3</code> instead of <code>pip</code>
| |
|
| |
| ====Navigating to the folder====
| |
|
| |
| * Open a command line (Windows: cmd.exe )
| |
| * Navigate to the folder you want to have PyPoE installed to/from
| |
| * Run <code>git clone https://github.com/OmegaK2/PyPoE.git</code>
| |
| * Go into the checkout folder where <code>setup.py</code> resides
| |
|
| |
| ====Running pip====
| |
|
| |
| To use the development install (it makes the files editable), specify <code>-e</code>.
| |
|
| |
| By default, PyPoE only installs the dependencies for the core (PyPoE.poe). However, there are additional packages available:
| |
| {| class="wikitable" | | {| class="wikitable" |
| ! Group | | ! Thing |
| ! description | | ! Description |
| |-
| | ! Command |
| | ui
| |
| | GUI support
| |
| |- | | |- |
| | cli | | | Modifier namespace pagse |
| | CLI support | | | all pages there should '''only''' be created by PyPoE |
| | | <code>pypoe_exporter wiki mods mods</code> |
| |- | | |- |
| | cli-wikibot | | | Base item pages |
| | Support for the --wiki option in the wiki exporter | | | All white items |
| | | <code>pypoe_exporter wiki items export</code> |
| |- | | |- |
| | dev | | | Prophecies |
| | Development libraries (i.e. for tests & generating documentation) | | | All prophecies |
| |} | | | <code>pypoe_exporter wiki items prophecy</code> |
| | |
| The base command for installing is:
| |
| | |
| <code>pip install -e .</code>
| |
| | |
| If you wish to add any extra packges, add them in a comma-separated list in brackets behind the dot:
| |
| | |
| <code>pip install -e .[ui,cli,cli-wikibot,dev]</code> | |
| | |
| ==Reporting an issue==
| |
| | |
| First, make sure the issue isn't known already:
| |
| * https://github.com/OmegaK2/PyPoE/issues
| |
| * check the individual files TODOs
| |
| | |
| If not, post an issue on github and provide the following
| |
| * title: short description of the bug
| |
| * detailed description of the bug
| |
| * if available, provide the relevant traceback
| |
| * if available, provide the relevant code that caused the bug (i.e. if your own code)
| |
| | |
| You can also submit pull requests that to help fix bugs, I'll review (and possibly) edit them. You agree they'll placed under the MIT license. Also see [[{{FULLPAGENAME}}#Contributing|Contributing]]
| |
| | |
| ==Contributing==
| |
| | |
| Everyone is generally welcome to contribute to the project.
| |
| | |
| There are basically 3 ways to do so:
| |
| * Feature requests & reporting issues
| |
| * Sending pull requests
| |
| * Becoming a dev
| |
| | |
| ===Pull requests===
| |
| | |
| You're welcome to send a pull request on github for features or changes you think that should be in PyPoE.
| |
| | |
| Please keep a few things in mind:
| |
| * the code in the request should be well behaved and a proper fix or addition
| |
| * the change should be under the MIT license
| |
| * if it's an entirely new feature, it may debatable whether it is has a place in PyPoE
| |
| * the submitted code should:
| |
| ** be well behaved and a proper fix or addition
| |
| ** be [https://www.python.org/dev/peps/pep-0008/ PEP8] compatible (minus the line-length)
| |
| ** include changes in the respective tests or new tests
| |
| ** validate against existing tests (if tests were changed, validate against those)
| |
| * backwards incompatible changes are more suited for the dev branch
| |
| | |
| So for example:
| |
| | |
| * Likely to be accepted
| |
| ** general improvements to existing code of UI, CLI or API
| |
| ** new, well-behaved features that extend the existing functional
| |
| ** support for missing file formats
| |
| ** updated dat.specification.ini
| |
| ** additional tests
| |
| * Likely to be rejected
| |
| ** changes unrelated to the goal of the project
| |
| ** refusal of making the change itself available under MIT license
| |
| ** changes with poor coding style
| |
| | |
| ===Become a dev===
| |
| | |
| If you want to become an '''active''' developer and meet the requirements please contact me. I'll manually unlock people for access to the repo.
| |
| | |
| Notes:
| |
| * If you just want to contribute a few changes, there is no need to become a dev and you can send pull requests instead.
| |
| * If you just want your own repo, just fork the project on github
| |
| | |
| Requirements:
| |
| * You should
| |
| ** have a good amount of experience with developing in Python 3
| |
| ** be willing to actively contribute, i.e. making changes on your own, working on the TODOs
| |
| ** be fluent in English (written); no you don't have to be a perfect speaker, but you're English should be good enough to have no issues with communication
| |
| ** be available in the IRC channel
| |
| * I'll want to see some pieces of code you've written; a good history of pull requests will suffice, otherwise:
| |
| ** another open source project you've been involved in,
| |
| ** some private things you've written but are willing to let me have a look at
| |
| | |
| It would be extra helpful, if you:
| |
| * have experience with C/C++ and writing embedded python libraries with C/API
| |
| * have a lot of experience with Path of Exile [for the api]
| |
| * are experienced with using Mediawiki [for exporter]
| |
| * speak other languages fluently or natively [for translating the project]
| |
| * are adept with reverse engineering [to help with api]
| |
| | |
| ==Structure==
| |
| | |
| {| class="wikitable"
| |
| ! Folder
| |
| ! Description
| |
| |- | | |- |
| | / | | | [[Module:QuestReward/data|quest rewards]] |
| | The root folder of the project
| | | Data containing the quest rewards given given after completing quests |
| |-
| | | <code>pypoe_exporter wiki item quest_rewards</code> |
| | /PyPoE/
| |
| | The root python folder
| |
| |-
| |
| | /PyPoE/_data/
| |
| | Shared data used by the other files. For example, the specifications for the .dat files reside there.
| |
| |- | |
| | /PyPoE/poe | |
| | The core API to work with Path of Exile; this will be of primary interest to other developers that want to use the API.
| |
| |-
| |
| | /PyPoE/shared | |
| | Core libraries and functions that are not specific to path of exile
| |
| |-
| |
| | /PyPoE/cli
| |
| | Libraries and functions for the command line interface of PyPoE
| |
| |- | | |- |
| | /PyPoE/ui | | | [[Module:QuestReward/vendor_reward_data|quest vendor rewards]] |
| | Libraries and functions for the QT4 based user interface of PyPoE
| | | Data containing the vendor quest rewards given after completing quests |
| |- | | | <code>pypoe_exporter wiki item vendor_rewards</code> |
| | /scripts/ | |
| | Collection of scripts intended to be invoked from the command line.
| |
| |-
| |
| | /tests/ | |
| | pytest based tests for the library and scripts
| |
| |} | | |} |
|
| |
|
|
| |
|
| [[Category:Development information]] | | [[Category:Development information]] |