mo2/pystubs-generation
0
0
Fork 0
mirror of https://github.com/ModOrganizer2/pystubs-generation.git synced 2026-07-27 14:07:13 -07:00
Code Issues Packages Projects Releases Wiki Activity

Add information on how to upload to pypi.

Browse Source
This commit is contained in:
Mikaël Capelle
2020-08-07 10:47:41 +02:00
parent c8c6e5d991
commit 94bd4bc6a0
6 changed files with 133 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+35 -33
View File
@@ -5,8 +5,11 @@ interface `mobase`.
## Using the stubs
If you do not want to generate them, the generated stubs are available under [`stubs/`](stubs/) for latest
versions of MO2.
You can install the `stubs` with `pip`:
```bash
pip install mobase-stubs
```
Some words of warning:
- The stubs are as correct as possible, but some errors are expected.
@@ -18,16 +21,6 @@ Some words of warning:
expected with these class (e.g., `isintance(myObject, QObject)` will return `False`), which is why a
`_object()` and `_widget()` method is also provided.
### Visual Studio Code
The `mobase` stubs can be used with [Visual Studio Code](https://code.visualstudio.com/) to enable auto-completion and eventually linting using `mypy`:
- To use the stubs for auto-completion, you can use the
[`python.autoComplete.extraPaths`](https://code.visualstudio.com/docs/python/editing#_enable-intellisense-for-custom-package-locations)
setting.
- If you want them to work with `mypy`, the easiest way is to create a `setup.cfg` file at the root of your
project (or any file that `mypy` recognize) and set the `mypy_path` property, see
[`mypy` documentation](https://mypy.readthedocs.io/en/stable/config_file.html#import-discovery).
## Generating the stubs
The stubs are generated using python by parsing the `mobase` module.
@@ -38,16 +31,13 @@ To generate the stubs, you can run:
```
# Change the output folder to whatever you want:
python main.py -c configs\config-2.3.0a10.json -o stubs\2.3.0a10\mobase.pyi ${MO2_INSTALL_PATH}
# [Optional] Run black on the file to get it clean:
black stubs\2.3.0a10\mobase.pyi
python main.py -c configs\config-2.3.yml -o stubs\2.3.0\mobase.pyi ${MO2_INSTALL_PATH}
```
Where `${MO2_INSTALL_PATH}` is the path to your MO2 installation (the one containing `ModOrganizer.exe`).
If you do not specify a `-o` option, output will go to `stdout`, so you should redirect. Warning and "critical"
messages are printed to `stderr`.
If you do not specify a `-o` option, output will go to `stdout`, so you should redirect.
Warning and "critical" messages are printed to `stderr`.
A few options are available for `main.py`:
@@ -68,34 +58,46 @@ optional arguments:
The stubs generator will try hard to find a valid stubs for all classes and methods of `mobase`.
A lot of information is available through the `-v` options. Without it, only conversions or fixes
considered "strange" will be outputed. For instance, here is the output with the current `config.json`
file:
considered "strange" will be outputed.
For instance, here is the output with the current `config-2.3.yml` file:
```
WARNING: Replacing IOrganizer::FileInfo with FileInfo.
WARNING: Replacing IOrganizer::FileInfo with FileInfo.
WARNING: Replacing IPluginInstaller::EInstallResult with InstallResult.
WARNING: Replacing IPluginInstaller::EInstallResult with InstallResult.
CRITICAL: Found bool * which is a pointer to a built-in python type.
```
As you can see, only a few types were manually fixed (specified in `config.json`), but a `bool *`
parameter was found, which is not valid, so this would require a change in the actual C++ bindings.
As you can see, only a few types were manually fixed (specified in `config-2.3.yml`).
## Configuration file
The configuration file contains information for the stubs that cannot be deduced by `main` (or are too
complex to deduce). In particular:
complex to deduce), and the documentation for everything.
- list of names to ignore - can be used to hide name or to ignore object for which stubs cannot be generated (currently
only stubs for classes can be generated, so functions are ignored);
- list of methods to override - can be used to override method signatures for methods that are too complex (see below);
- list of property types - should be used to specify the types of the property since these cannot be deduced;
- list of bases - should be used to override the bases of a class (e.g., to add `QObject`);
- list of Qt signals - should be used to indicate available signals (new ones).
## Uploading the stubs to pypi
The upload of the stubs to https://pypi.org/project/mobase-stubs/ has to be done manually. Here
are the steps:
1. Check the version of the stubs:
- The version is specified in the configuration file. If you need to modify the stubs of the
current version, you need to add a `.postX` after the version since PyPi does not allow
re-upload of the same release.
2. Generate the stubs using the procedure above. Currently, stubs are stored under `stubs/x.y.z/mobase.pyi`
for each release of MO2.
3. Copy the `stubs/x.y.z/mobase.pyi` stubs to `stubs/setup/mobase-stubs/__init__.pyi`.
4. If necessary, update the dependencies in `setup.py` (`PyQt5-stubs` version and python version).
5. Go to `stubs/setup` and run:
```bash
python setup.py sdist bdist_wheel
twine upload dist/*
```
You need to set the environment variables `TWINE_USERNAME` and `TWINE_PASSWORD` to appropriate values
before running `twine upload`.
An example of configuration file is [`config.json`](config.json), and an empty configuration is provided ([`empty.json`](empty.json))
to show what happens with an empty configuration.
## Extras — Starts a python interpreter with `mobase`
@@ -111,7 +113,7 @@ This has no real usage except for MO2 developers since most classes from the `mo
The MIT License (MIT)
Copyright (c) 2020, Mikaël Capelle.
Copyright (c) 2020, Holt59.
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:
stubs/setup/.gitignore
+4
View File
@@ -0,0 +1,4 @@
build
dist
mobase-stubs/__init__.pyi
mobase_stubs.egg-info
stubs/setup/LICENSE
+21
View File
@@ -0,0 +1,21 @@
Copyright 2020 © Holt59
The MIT License (MIT)
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.
stubs/setup/README.md
+16
View File
@@ -0,0 +1,16 @@
<img src="http://mypy-lang.org/static/mypy_light.svg" alt="mypy logo" width="300px"/>
[![PyPI version](https://badge.fury.io/py/mobase-stubs.svg)](https://badge.fury.io/py/mobase-stubs)
[![mypy checked](https://camo.githubusercontent.com/34b3a249cd6502d0a521ab2f42c8830b7cfd03fa/687474703a2f2f7777772e6d7970792d6c616e672e6f72672f7374617469632f6d7970795f62616467652e737667)](http://mypy-lang.org/)
# Mypy stubs for the mobase Python API
This repository holds the stubs of the `mobase` python module, which contains the Python plugin
interface for [Mod Organizer 2](https://github.com/modorganizer2/modorganizer) plugins.
It uses the stub files that are produced by https://github.com/ModOrganizer2/pystubs-generation/.
# Installation
Simply install `mobase-stubs` with pip:
$ pip install `mobase-stubs`
stubs/setup/mobase-stubs/.keep
View File
stubs/setup/setup.py
+57
View File
@@ -0,0 +1,57 @@
"""Python setup script.
:author: Stefan Lehmann <stlm@posteo.de>
:license: MIT, see license file or https://opensource.org/licenses/MIT
:created on 2018-10-06 10:55:36
:last modified by: Stefan Lehmann
:last modified time: 2019-07-23 10:27:04
"""
import io
import os
import re
from setuptools import setup
def read(*names, **kwargs):
try:
with io.open(
os.path.join(os.path.dirname(__file__), *names),
encoding=kwargs.get("encoding", "utf8"),
) as fp:
return fp.read()
except IOError:
return ""
def find_version(*file_paths):
version_file = read(*file_paths)
version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]", version_file, re.M)
if version_match:
return version_match.group(1)
raise RuntimeError("Unable to find version string.")
long_description = read("README.md")
setup(
name="mobase-stubs",
url="https://github.com/ModOrganizer2/mo2-pystubs-generation",
author="Holt59",
description="PEP561 stub files for the mobase python API",
long_description=long_description,
long_description_content_type="text/markdown",
version=find_version("mobase-stubs", "__init__.pyi"),
package_data={"mobase-stubs": ["*.pyi"]},
packages=["mobase-stubs"],
install_requires=["PyQt5-stubs==5.14.2"],
python_requires="==3.8.*",
classifiers=[
"Intended Audience :: Developers",
"Programming Language :: Python :: 3.8",
"License :: OSI Approved :: MIT License",
"Topic :: Software Development",
],
)