Basic documentation for pymojang

docs/advanced.md

@@ -0,0 +1,86 @@
+# PyMojang - Advanced Usage
+
+## Full profile
+
+To get all the available data about a user, use the function [`user`](). It will return a [`UserProfile`]() object
+
+```python
+import mojang
+
+profile = mojang.user(username='Notch')
+
+# OR
+
+profile = mojang.user(uuid='069a79f444e94726a5befca90e38aaf5')
+```
+
+Once done, you have access to the following attributes:
+
+- `uuid` **(str)** : The uuid of the profile
+- `name` **(str)** : The name of the profile
+- `is_legacy` **(bool)** : If the account has migrated to Mojang
+- `is_demo` **(bool)** : If the account is a demo account
+- `names` **(list)** : The name history of the profile
+- `skins` **(list)** : The skins of the profiles
+- `capes` **(list)** : The capes of the profiles
+
+
+## Authenticated User
+
+To connect with a **username** and **password**, use the function [`connect`](). It will return a [`UserSession`]() object.
+
+The [`connect`]() function also take a **client_token** parameter, but it's optional. It will be, by default, automaticly generated.
+
+```python
+session = mojang.connect('YOUR_USERNAME','YOUR_PASSWORD')
+```
+
+Once authenticated, you will have access to all the profile's attributes and also to the following new attributes:
+
+- `name_change_allowed` **(bool)** : If the account can change name
+- `created_at` **(datetime.datetime)** : the date and time at which the profile was created
+
+You will also have access to the following methods:
+
+- [`change_name`]() : Change the account username
+- [`change_skin`]() : Change the account skin
+- [`reset_skin`]() : Reset the account skin to the default one
+
+### Security
+
+The first time you are going to try to connect to your account you might have some problem with certain fonctionnality, and this is because your **IP** is no verified. See [Security Question Answer Flow](https://wiki.vg/Mojang_API#Security_question-answer_flow).
+
+Once your authenticated, you can check if your IP is secure with the `secure` attribute:  
+
+```python
+if not session.secure:
+    # Do something
+```
+
+If your IP is not secure, you must complete the challenges (questions). You can get them like so:
+
+```python
+session.challenges
+```
+
+Each challenge is a tuple, the first item is the answer's id and the second one is the challenge:
+
+```python
+[
+    (123, "What is your favorite pet's name?"),
+    (456, "What is your favorite movie?"),
+    (789, "What is your favorite author's last name?")
+]
+```
+
+To verify your ip, you must send your answers, they must have the same format as the questions:
+
+```python
+answers = [
+    (123, "foo"),
+    (456, "bar"),
+    (789, "baz")
+]
+
+session.verify(answers)
+```

docs/basic.md

@@ -0,0 +1,99 @@
+# PyMojang - Basic Usage
+
+## API Status
+
+To get the status of each Mojang services, use the function [`api_status`]()
+
+```python
+import mojang
+
+status = mojang.api_status()
+```
+
+```json
+{
+    "minecraft.net": "green", 
+    "session.minecraft.net": "green", 
+    "account.mojang.com": "green", 
+    "authserver.mojang.com": "green", 
+    "sessionserver.mojang.com": "red", 
+    "api.mojang.com": "green", 
+    "textures.minecraft.net": "green", 
+    "mojang.com": "green"
+}
+```
+
+By specifying the name of a service, the function will only return the status for this service
+
+```python
+import mojang
+
+status = mojang.api_status('minecraft.net')
+```
+
+```bash
+green
+```
+
+## UUID by Username
+
+To get the UUID of a username, use the function [`get_uuid`]()
+
+```python
+import mojang
+
+uuid = mojang.get_uuid('Notch')
+```
+
+```bash
+069a79f444e94726a5befca90e38aaf5
+```
+
+
+## UUIDs by Usernames
+
+To get the UUID for multiple usernames, use the function [`get_uuids`]()
+
+!!! note
+    The Mojang API endpoint only allow 10 usernames, if more than 10 usernames are given to the function, multiple request will be made.
+
+```python
+import mojang
+
+uuids = mojang.get_uuids(['Notch','jeb_'])
+```
+
+```bash
+['069a79f444e94726a5befca90e38aaf5','853c80ef3c3749fdaa49938b674adae6']
+```
+
+## Username by UUID
+
+To get the username for a UUID, use the function [`get_username`]()
+
+```python
+import mojang
+
+username = mojang.get_username('069a79f444e94726a5befca90e38aaf5')
+```
+
+```bash
+Notch
+```
+
+## Name History
+
+To get the name history for a specific user, use the function [`name_history`]()
+
+```python
+import mojang
+
+names = mojang.name_history('65a8dd127668422e99c2383a07656f7a')
+```
+
+```python
+[
+    ('piewdipie', None), 
+    ('KOtMotros', datetime.datetime(2020, 3, 4, 18, 45, 26))
+]
+```

docs/index.md

@@ -0,0 +1,14 @@
+# PyMojang - Documentation
+
+PyMojang is a full wrapper of the [Mojang API](https://wiki.vg/Mojang_API) and [Mojang Authentication API](https://wiki.vg/Authentication).
+
+You can retrieve basic user information such as their ***uuid***, ***skin***, ***cape***,...
+
+Thanks to the **Authentication API**, you can also connect to your account and have access to more data and functionalities like **change your name and your skin**. It also gives you access to a token that can be used when your are making a **launcher**.
+
+## Install
+
+You can simply install PyMojang with:
+```bash
+pip install pymojang
+```

mkdocs.yml

@@ -0,0 +1,23 @@
+site_name: PyMojang
+
+theme: readthedocs
+
+markdown_extensions:
+  - admonition
+
+nav:
+  - Quisk Start:
+    - Installation: 'index.md'
+    - Basic Usage: 'basic.md'
+
+  - Advanced:
+    - Profile and Authentication: 'advanced.md'
+
+  - PyMojang:
+    - mojang.api.auth.yggdrasil: '/PyMojang/yggdrasil.md'
+    - mojang.api.auth.security: '/PyMojang/secuity.md'
+    - mojang.api.base: '/PyMojang/base.md'
+    - mojang.api.session: '/PyMojang/session.md'
+    - mojang.profile.UserProfile: '/PyMojang/UserProfile.md'
+    - mojang.session.UserSession: '/PyMojang/UserSession.md' 
+    - Exceptions: '/PyMojang/exceptions.md'