python-xbox 0.1.0__tar.gz

python_xbox-0.1.0/.gitignore

@@ -0,0 +1,76 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+.env
+.venv/
+venv/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+#Virtualenv folders and files
+Scripts
+pyvenv.cfg
+Lib
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Intellij
+.idea/
+
+# VS Code
+.vscode/
+
+# Node
+node_modules
+

python_xbox-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2025 Manfred Dennerlein Rodelo
+Copyright (c) 2020 - 2025 OpenXbox
+
+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.

python_xbox-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: python-xbox
+Version: 0.1.0
+Summary: A library to authenticate with Xbox Network and use their API
+Project-URL: Source, https://github.com/tr4nt0r/python-xbox
+Author: OpenXbox
+Author-email: Manfred Dennerlein Rodelo <manfred@dennerlein.name>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: xbox one live api
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: ecdsa
+Requires-Dist: httpx
+Requires-Dist: ms-cv
+Requires-Dist: pydantic==2.*
+Provides-Extra: cli
+Requires-Dist: platformdirs>=4.5.0; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# python-xbox
+
+[![PyPi - latest](https://img.shields.io/pypi/v/python-xbox.svg)](https://pypi.python.org/pypi/python-xbox/)
+[![Build](https://github.com/tr4nt0r/python-xbox/actions/workflows/build.yml/badge.svg)](https://github.com/tr4nt0r/python-xbox/actions/workflows/build.yml)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/python-xbox?style=flat&label=pypi%20downloads)
+[!["Buy Me A Coffee"](https://img.shields.io/badge/-buy_me_a%C2%A0coffee-gray?logo=buy-me-a-coffee)](https://www.buymeacoffee.com/tr4nt0r)
+[![GitHub Sponsor](https://img.shields.io/badge/GitHub-Sponsor-blue?logo=github)](https://github.com/sponsors/tr4nt0r)
+
+python-xbox is a python library to authenticate with Xbox Network via your Microsoft Account and provides Xbox related Web-API.
+
+Authentication is supported via OAuth2.
+
+- Register a new application in [Azure AD](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
+  - Name your app
+  - Select "Personal Microsoft accounts only" under supported account types
+  - Add <http://localhost/auth/callback> as a Redirect URI of type "Web"
+- Copy your Application (client) ID for later use
+- On the App Page, navigate to "Certificates & secrets"
+  - Generate a new client secret and save for later use
+
+## Dependencies
+
+- Python >= 3.11
+
+## How to use
+
+### Install
+
+```bash
+pip install python-xbox
+```
+
+### Authentication
+
+> [!NOTE]
+> You must use non child account (> 18 years old)
+
+Token save location: If tokenfile is not provided via cmdline, fallback of `<platformdirs.user_data_dir>/tokens.json` is used as save-location
+
+Specifically:
+
+Windows: `C:\\Users\\<username>\\AppData\\Local\\OpenXbox\\xbox`
+
+Mac OSX: `/Users/<username>/Library/Application Support/xbox/tokens.json`
+
+Linux: `/home/<username>/.local/share/xbox`
+
+For more information, see: <https://pypi.org/project/platformdirs> and module: `python-xbox.scripts.constants`
+
+```bash
+xbox-authenticate --client-id <client-id> --client-secret <client-secret>
+```
+
+Example: Search Xbox Live via cmdline tool
+
+```bash
+  # Search Xbox One Catalog
+  xbox-searchlive "Some game title"
+```
+
+API usage
+
+```python
+import asyncio
+import sys
+
+from httpx import HTTPStatusError
+
+from pythonxbox.api.client import XboxLiveClient
+from pythonxbox.authentication.manager import AuthenticationManager
+from pythonxbox.authentication.models import OAuth2TokenResponse
+from pythonxbox.common.signed_session import SignedSession
+from pythonxbox.scripts import CLIENT_ID, CLIENT_SECRET, TOKENS_FILE
+
+"""
+This uses the global default client identification by OpenXbox
+You can supply your own parameters here if you are permitted to create
+new Microsoft OAuth Apps and know what you are doing
+"""
+client_id = CLIENT_ID
+client_secret = CLIENT_SECRET
+tokens_file = TOKENS_FILE
+
+"""
+For doing authentication, see pythonxbox/scripts/authenticate.py
+"""
+
+
+async def async_main():
+    # Create a HTTP client session
+    async with SignedSession() as session:
+        """
+        Initialize with global OAUTH parameters from above
+        """
+        auth_mgr = AuthenticationManager(session, client_id, client_secret, "")
+
+        """
+        Read in tokens that you received from the `xbox-authenticate`-script previously
+        See `pythonxbox/scripts/authenticate.py`
+        """
+        try:
+            with open(tokens_file) as f:
+                tokens = f.read()
+            # Assign gathered tokens
+            auth_mgr.oauth = OAuth2TokenResponse.model_validate_json(tokens)
+        except FileNotFoundError as e:
+            print(
+                f"File {tokens_file} isn`t found or it doesn`t contain tokens! err={e}"
+            )
+            print("Authorizing via OAUTH")
+            url = auth_mgr.generate_authorization_url()
+            print(f"Auth via URL: {url}")
+            authorization_code = input("Enter authorization code> ")
+            tokens = await auth_mgr.request_oauth_token(authorization_code)
+            auth_mgr.oauth = tokens
+
+        """
+        Refresh tokens, just in case
+        You could also manually check the token lifetimes and just refresh them
+        if they are close to expiry
+        """
+        try:
+            await auth_mgr.refresh_tokens()
+        except HTTPStatusError as e:
+            print(
+                f"""
+                Could not refresh tokens from {tokens_file}, err={e}\n
+                You might have to delete the tokens file and re-authenticate 
+                if refresh token is expired
+            """
+            )
+            sys.exit(-1)
+
+        # Save the refreshed/updated tokens
+        with open(tokens_file, mode="w") as f:
+            f.write(auth_mgr.oauth.json())
+        print(f"Refreshed tokens in {tokens_file}!")
+
+        """
+        Construct the Xbox API client from AuthenticationManager instance
+        """
+        xbl_client = XboxLiveClient(auth_mgr)
+
+        """
+        Some example API calls
+        """
+        # Get friendslist
+        friendslist = await xbl_client.people.get_friends_own()
+        print(f"Your friends: {friendslist}\n")
+
+        # Get presence status (by list of XUID)
+        presence = await xbl_client.presence.get_presence_batch(
+            ["2533274794093122", "2533274807551369"]
+        )
+        print(f"Statuses of some random players by XUID: {presence}\n")
+
+        # Get messages
+        messages = await xbl_client.message.get_inbox()
+        print(f"Your messages: {messages}\n")
+
+        # Get profile by GT
+        profile = await xbl_client.profile.get_profile_by_gamertag("SomeGamertag")
+        print(f"Profile under SomeGamertag gamer tag: {profile}\n")
+
+
+asyncio.run(async_main())
+```
+
+## Contribute
+
+- Report bugs/suggest features
+- Add/update docs
+- Add additional xbox live endpoints
+
+## Credits
+
+This library is derived from [xbox-webapi](https://github.com/OpenXbox/xbox-webapi-python) library from the [OpenXbox](https://github.com/openxbox) project
+The authentication code is based on [joealcorn/xbox](https://github.com/joealcorn/xbox)
+
+Informations on endpoints gathered from:
+
+- [XboxLive REST Reference](https://docs.microsoft.com/en-us/windows/uwp/xbox-live/xbox-live-rest/atoc-xboxlivews-reference)
+- [XboxLiveTraceAnalyzer APIMap](https://github.com/Microsoft/xbox-live-trace-analyzer/blob/master/Source/XboxLiveTraceAnalyzer.APIMap.csv)
+- [Xbox Live Service API](https://github.com/Microsoft/xbox-live-api)
+
+## Disclaimer
+
+Xbox, Xbox One, Smartglass and Xbox Live are trademarks of Microsoft Corporation. Team OpenXbox is in no way endorsed by or affiliated with Microsoft Corporation, or any associated subsidiaries, logos or trademarks.

python_xbox-0.1.0/README.md

@@ -0,0 +1,188 @@
+# python-xbox
+
+[![PyPi - latest](https://img.shields.io/pypi/v/python-xbox.svg)](https://pypi.python.org/pypi/python-xbox/)
+[![Build](https://github.com/tr4nt0r/python-xbox/actions/workflows/build.yml/badge.svg)](https://github.com/tr4nt0r/python-xbox/actions/workflows/build.yml)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/python-xbox?style=flat&label=pypi%20downloads)
+[!["Buy Me A Coffee"](https://img.shields.io/badge/-buy_me_a%C2%A0coffee-gray?logo=buy-me-a-coffee)](https://www.buymeacoffee.com/tr4nt0r)
+[![GitHub Sponsor](https://img.shields.io/badge/GitHub-Sponsor-blue?logo=github)](https://github.com/sponsors/tr4nt0r)
+
+python-xbox is a python library to authenticate with Xbox Network via your Microsoft Account and provides Xbox related Web-API.
+
+Authentication is supported via OAuth2.
+
+- Register a new application in [Azure AD](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
+  - Name your app
+  - Select "Personal Microsoft accounts only" under supported account types
+  - Add <http://localhost/auth/callback> as a Redirect URI of type "Web"
+- Copy your Application (client) ID for later use
+- On the App Page, navigate to "Certificates & secrets"
+  - Generate a new client secret and save for later use
+
+## Dependencies
+
+- Python >= 3.11
+
+## How to use
+
+### Install
+
+```bash
+pip install python-xbox
+```
+
+### Authentication
+
+> [!NOTE]
+> You must use non child account (> 18 years old)
+
+Token save location: If tokenfile is not provided via cmdline, fallback of `<platformdirs.user_data_dir>/tokens.json` is used as save-location
+
+Specifically:
+
+Windows: `C:\\Users\\<username>\\AppData\\Local\\OpenXbox\\xbox`
+
+Mac OSX: `/Users/<username>/Library/Application Support/xbox/tokens.json`
+
+Linux: `/home/<username>/.local/share/xbox`
+
+For more information, see: <https://pypi.org/project/platformdirs> and module: `python-xbox.scripts.constants`
+
+```bash
+xbox-authenticate --client-id <client-id> --client-secret <client-secret>
+```
+
+Example: Search Xbox Live via cmdline tool
+
+```bash
+  # Search Xbox One Catalog
+  xbox-searchlive "Some game title"
+```
+
+API usage
+
+```python
+import asyncio
+import sys
+
+from httpx import HTTPStatusError
+
+from pythonxbox.api.client import XboxLiveClient
+from pythonxbox.authentication.manager import AuthenticationManager
+from pythonxbox.authentication.models import OAuth2TokenResponse
+from pythonxbox.common.signed_session import SignedSession
+from pythonxbox.scripts import CLIENT_ID, CLIENT_SECRET, TOKENS_FILE
+
+"""
+This uses the global default client identification by OpenXbox
+You can supply your own parameters here if you are permitted to create
+new Microsoft OAuth Apps and know what you are doing
+"""
+client_id = CLIENT_ID
+client_secret = CLIENT_SECRET
+tokens_file = TOKENS_FILE
+
+"""
+For doing authentication, see pythonxbox/scripts/authenticate.py
+"""
+
+
+async def async_main():
+    # Create a HTTP client session
+    async with SignedSession() as session:
+        """
+        Initialize with global OAUTH parameters from above
+        """
+        auth_mgr = AuthenticationManager(session, client_id, client_secret, "")
+
+        """
+        Read in tokens that you received from the `xbox-authenticate`-script previously
+        See `pythonxbox/scripts/authenticate.py`
+        """
+        try:
+            with open(tokens_file) as f:
+                tokens = f.read()
+            # Assign gathered tokens
+            auth_mgr.oauth = OAuth2TokenResponse.model_validate_json(tokens)
+        except FileNotFoundError as e:
+            print(
+                f"File {tokens_file} isn`t found or it doesn`t contain tokens! err={e}"
+            )
+            print("Authorizing via OAUTH")
+            url = auth_mgr.generate_authorization_url()
+            print(f"Auth via URL: {url}")
+            authorization_code = input("Enter authorization code> ")
+            tokens = await auth_mgr.request_oauth_token(authorization_code)
+            auth_mgr.oauth = tokens
+
+        """
+        Refresh tokens, just in case
+        You could also manually check the token lifetimes and just refresh them
+        if they are close to expiry
+        """
+        try:
+            await auth_mgr.refresh_tokens()
+        except HTTPStatusError as e:
+            print(
+                f"""
+                Could not refresh tokens from {tokens_file}, err={e}\n
+                You might have to delete the tokens file and re-authenticate 
+                if refresh token is expired
+            """
+            )
+            sys.exit(-1)
+
+        # Save the refreshed/updated tokens
+        with open(tokens_file, mode="w") as f:
+            f.write(auth_mgr.oauth.json())
+        print(f"Refreshed tokens in {tokens_file}!")
+
+        """
+        Construct the Xbox API client from AuthenticationManager instance
+        """
+        xbl_client = XboxLiveClient(auth_mgr)
+
+        """
+        Some example API calls
+        """
+        # Get friendslist
+        friendslist = await xbl_client.people.get_friends_own()
+        print(f"Your friends: {friendslist}\n")
+
+        # Get presence status (by list of XUID)
+        presence = await xbl_client.presence.get_presence_batch(
+            ["2533274794093122", "2533274807551369"]
+        )
+        print(f"Statuses of some random players by XUID: {presence}\n")
+
+        # Get messages
+        messages = await xbl_client.message.get_inbox()
+        print(f"Your messages: {messages}\n")
+
+        # Get profile by GT
+        profile = await xbl_client.profile.get_profile_by_gamertag("SomeGamertag")
+        print(f"Profile under SomeGamertag gamer tag: {profile}\n")
+
+
+asyncio.run(async_main())
+```
+
+## Contribute
+
+- Report bugs/suggest features
+- Add/update docs
+- Add additional xbox live endpoints
+
+## Credits
+
+This library is derived from [xbox-webapi](https://github.com/OpenXbox/xbox-webapi-python) library from the [OpenXbox](https://github.com/openxbox) project
+The authentication code is based on [joealcorn/xbox](https://github.com/joealcorn/xbox)
+
+Informations on endpoints gathered from:
+
+- [XboxLive REST Reference](https://docs.microsoft.com/en-us/windows/uwp/xbox-live/xbox-live-rest/atoc-xboxlivews-reference)
+- [XboxLiveTraceAnalyzer APIMap](https://github.com/Microsoft/xbox-live-trace-analyzer/blob/master/Source/XboxLiveTraceAnalyzer.APIMap.csv)
+- [Xbox Live Service API](https://github.com/Microsoft/xbox-live-api)
+
+## Disclaimer
+
+Xbox, Xbox One, Smartglass and Xbox Live are trademarks of Microsoft Corporation. Team OpenXbox is in no way endorsed by or affiliated with Microsoft Corporation, or any associated subsidiaries, logos or trademarks.

python_xbox-0.1.0/pyproject.toml

@@ -0,0 +1,125 @@
+[project]
+name = "python-xbox"
+description = "A library to authenticate with Xbox Network and use their API"
+authors = [
+    {name = "Manfred Dennerlein Rodelo", email = "manfred@dennerlein.name"},
+    {name = "OpenXbox"},
+]
+dependencies = [
+    "ecdsa",
+    "httpx",
+    "ms_cv",
+    "pydantic==2.*",
+]
+requires-python = ">=3.11"
+readme = "README.md"
+license = "MIT"
+keywords = ["xbox one live api"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dynamic = ["version"]
+
+[project.urls]
+Source = "https://github.com/tr4nt0r/python-xbox"
+
+[project.optional-dependencies]
+cli = [
+    "platformdirs>=4.5.0"
+]
+
+[project.scripts]
+xbox-authenticate = "pythonxbox.scripts.authenticate:main"
+xbox-change-gt = "pythonxbox.scripts.change_gamertag:main"
+xbox-friends = "pythonxbox.scripts.friends:main"
+xbox-searchlive = "pythonxbox.scripts.search:main"
+xbox-xal = "pythonxbox.scripts.xal:main"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "UP", "S", "ANN"]
+# select = ["ALL"]
+ignore = ["ANN003", "ANN401"]
+
+
+[tool.ruff.lint.per-file-ignores]
+"**/scripts/*" = ["UP", "S104"]
+"tests/*" = ["S101"]
+"src/pythonxbox/authentication/xal.py" = ["S101"]
+
+[tool.ruff.lint.isort]
+force-sort-within-sections = true
+known-first-party = ["pythonxbox"]
+combine-as-imports = true
+split-on-trailing-comma = false
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.hatch.version]
+source = "regex_commit"
+commit_extra_args = ["-e"]
+path = "src/pythonxbox/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/pythonxbox",
+]
+[tool.hatch.build.targets.wheel]
+packages = ["src/pythonxbox"]
+
+[tool.hatch.envs.default]
+python = "3.13"
+dependencies = [
+    "platformdirs==4.5.0",
+    "ecdsa==0.19.1",
+    "httpx==0.28.1",
+    "ms_cv==0.1.1",
+    "pydantic==2.12.3",
+    "pytest==8.4.2",
+    "pytest-asyncio==1.2.0",
+    "pytest-cov==7.0.0",
+    "freezegun==1.5.5",
+    "respx~=0.22",
+]
+
+[tool.hatch.envs.hatch-test]
+parallel = true
+extra-dependencies = [
+  "pytest-cov~=6.2",
+  "pytest-asyncio~=1.1",
+  "respx~=0.22",
+  "freezegun==1.5.5"
+]
+extra-args = ["--cov=src/", "--cov-report=term-missing", "--cov-report=xml", "-vv"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[[tool.hatch.envs.hatch-test.matrix]]
+python = ["3.14", "3.13", "3.12", "3.11"]
+
+[tool.hatch.envs.hatch-static-analysis]
+dependencies = [
+    "ruff==0.14.2",
+]
+config-path = "none"
+
+[build-system]
+requires = ["hatchling", "hatch-regex-commit"]
+build-backend = "hatchling.build"

python_xbox-0.1.0/src/pythonxbox/__init__.py

@@ -0,0 +1,4 @@
+"""Top-level package for python-xbox."""
+
+__author__ = """tr4nt0r"""
+__version__ = "0.1.0"