jenkins-bot has submitted this change. (
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/738576 )
Change subject: [IMP] Make a pywikibot entry point for scripts
......................................................................
[IMP] Make a pywikibot entry point for scripts
- add pwb.py wrapper script to the site-package. This enables scripts to be
invoked whose paths were added to the config.user_script_paths inside
user-config.py. Further implementations can provide entry points of
foreign pypi packages. The pwb.py script will be copied to the new
pywikibot.scripts folder when creating a dist.
- Add a new pywikibot.scripts folder to the framework
- move version.py script from scripts folder to pywikibot.scripts
to enable version call within site-package
- add a code entry point in setup that pwb.py wrapper script can be
always called with "pwb" within every folder
- update documentation in several files
pwb.py
- rename main() function to execute
- move check_modules call to main() function
- add run() function as entry point for site-package and don't check
package dependencies for a site-package because it is already done
during installation
- use base_dir instead of _pwb_dir for testpath path
- add _pwb_dir to script_paths if pywikibot is a site-package,
otherwise add pywikibot.scripts
Bug: T270480
Bug: T139143
Change-Id: I51160dc4df95b59bac98acf9f4e170232c4923a2
---
M README.rst
M docs/api_ref/pywikibot.config.rst
M docs/scripts/scripts.rst
M docs/utilities/index.rst
M pwb.py
M pywikibot/CONTENT.rst
M pywikibot/DIRECTORIES.rst
M pywikibot/config.py
A pywikibot/scripts/__init__.py
R pywikibot/scripts/version.py
M scripts/README.rst
M setup.py
12 files changed, 107 insertions(+), 26 deletions(-)
Approvals:
Xqt: Looks good to me, approved
jenkins-bot: Verified
diff --git a/README.rst b/README.rst
index 4a02555..eebbf97 100644
--- a/README.rst
+++ b/README.rst
@@ -50,6 +50,7 @@
pip install -U setuptools
pip install pywikibot
+ pwb <scriptname>
In addition a MediaWiki markup parser is required. Please install one of them:
diff --git a/docs/api_ref/pywikibot.config.rst b/docs/api_ref/pywikibot.config.rst
index 290636c..c31852a 100644
--- a/docs/api_ref/pywikibot.config.rst
+++ b/docs/api_ref/pywikibot.config.rst
@@ -39,6 +39,8 @@
:start-at: # ############# LOGFILE SETTINGS
:end-before: # #############
+.. _external-script-path-settings:
+
External Script Path Settings
+++++++++++++++++++++++++++++
diff --git a/docs/scripts/scripts.rst b/docs/scripts/scripts.rst
index 6a9371a..86ec7d3 100644
--- a/docs/scripts/scripts.rst
+++ b/docs/scripts/scripts.rst
@@ -252,11 +252,6 @@
.. automodule:: scripts.upload
-version script
---------------
-
-.. automodule:: scripts.version
-
watchlist script
----------------
diff --git a/docs/utilities/index.rst b/docs/utilities/index.rst
index 96131fa..9965397 100644
--- a/docs/utilities/index.rst
+++ b/docs/utilities/index.rst
@@ -6,6 +6,11 @@
.. automodule:: pwb
+version script
+--------------
+
+.. automodule:: pywikibot.scripts.version
+
generate\_family\_file script
-----------------------------
diff --git a/pwb.py b/pwb.py
index b8ddd82..3f23bc3 100755
--- a/pwb.py
+++ b/pwb.py
@@ -2,10 +2,27 @@
# -*- coding: utf-8 -*-
"""Wrapper script to invoke pywikibot-based scripts.
+This wrapper script invokes script by its name in this search order:
+
+1. Scripts listed in `user_script_paths` list inside your `user-config.py`
+ settings file in the given order. Refer
+ :ref:`External Script Path Settings<external-script-path-settings>`.
+2. User scripts residing in `scripts/userscripts` (directory mode only).
+3. Scripts residing in `scripts` folder (directory mode only).
+4. Maintenance scripts residing in `scripts/maintenance` (directory mode only).
+5. Framework scripts residing in `pywikibot/scripts`.
+
+This wrapper script is able to invoke scripts even the script name is
+missspelled. In directory mode it also checks package dependencies.
+
Run scripts with pywikibot in directory mode using::
python pwb.py <pwb options> <name_of_script> <options>
+or run scripts with pywikibot installed as a site package using::
+
+ pwb <pwb options> <name_of_script> <options>
+
This wrapper script uses the package directory to store all user files,
will fix up search paths so the package does not need to be installed, etc.
@@ -13,6 +30,9 @@
for tests to set the default site (see T216825)::
python pwb.py -lang:de bot_tests -v
+
+.. versionchanged:: 7.0
+ pwb wrapper was added to the Python site package lib
"""
# (C) Pywikibot team, 2012-2021
#
@@ -32,6 +52,7 @@
pwb = None
+site_package = False
def check_pwb_versions(package):
@@ -235,12 +256,6 @@
return not missing_requirements
-try:
- if not check_modules():
- raise RuntimeError('') # no further output needed
-except RuntimeError as e: # setup.py may also raise RuntimeError
- sys.exit(e)
-
from pathlib import Path # noqa: E402
@@ -333,9 +348,15 @@
"""Search for the filename in the given script
paths."""
from pywikibot import config
- script_paths = ['scripts.userscripts',
- 'scripts',
- 'scripts.maintenance']
+ if site_package:
+ script_paths = [_pwb_dir]
+ else:
+ script_paths = [
+ 'scripts.userscripts',
+ 'scripts',
+ 'scripts.maintenance',
+ 'pywikibot.scripts',
+ ]
if config.user_script_paths:
if isinstance(config.user_script_paths, list):
@@ -349,7 +370,7 @@
for file_package in script_paths:
package = file_package.split('.')
paths = package + [filename]
- testpath = os.path.join(_pwb_dir, *paths)
+ testpath = os.path.join(config.base_dir, *paths)
if os.path.exists(testpath):
filename = testpath
break
@@ -359,8 +380,12 @@
return filename
-def main():
- """Command line entry point."""
+def execute():
+ """Parse arguments, extract filename and run the script.
+
+ .. versionadded:: 7.0
+ renamed from :func:`main`
+ """
global filename
if global_args: # don't use sys.argv
@@ -419,6 +444,32 @@
return True
-if __name__ == '__main__':
- if not main():
+def main():
+ """Script entry point. Print doc if necessary.
+
+ .. versionchanged:: 7.0
+ previous implementation was renamed to :func:`execute`
+ """
+ try:
+ if not check_modules():
+ raise RuntimeError('') # no further output needed
+ except RuntimeError as e: # setup.py may also raise RuntimeError
+ sys.exit(e)
+
+ if not execute():
print(__doc__)
+
+
+def run():
+ """Site package entry point. Print doc if necessary.
+
+ .. versionadded:: 7.0
+ """
+ global site_package
+ site_package = True
+ if not execute():
+ print(__doc__)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/pywikibot/CONTENT.rst b/pywikibot/CONTENT.rst
index e4398a8..deb5c3e 100644
--- a/pywikibot/CONTENT.rst
+++ b/pywikibot/CONTENT.rst
@@ -113,6 +113,16 @@
+----------------------------+------------------------------------------------------+
+ | scripts | Framework helper scripts and entry points
|
+
+============================+======================================================+
+ | pwb.py | code entry wrapper script (site-package only)
|
+
+----------------------------+------------------------------------------------------+
+ | version.py | Outputs Pywikibot's revision number, Python's
|
+ | | version and OS used.
|
+
+----------------------------+------------------------------------------------------+
+
+
+
+----------------------------+------------------------------------------------------+
| site | Module with classes for MediaWiki sites
|
+============================+======================================================+
| __init__.py | Objects representing MediaWiki sites (wikis)
|
diff --git a/pywikibot/DIRECTORIES.rst b/pywikibot/DIRECTORIES.rst
index d2b3c1b..0e930a6 100644
--- a/pywikibot/DIRECTORIES.rst
+++ b/pywikibot/DIRECTORIES.rst
@@ -14,6 +14,8 @@
+---------------------------+------------------------------------------------------+
| pywikibot/page | Module with classes for MediaWiki page content |
+---------------------------+------------------------------------------------------+
+ | pywikibot/scripts | Framework helper scripts |
+ +---------------------------+------------------------------------------------------+
| pywikibot/site | Module with classes for MediaWiki sites |
+---------------------------+------------------------------------------------------+
| pywikibot/specialbots | Module containing special bots reusable by scripts |
diff --git a/pywikibot/config.py b/pywikibot/config.py
index d573ada..beff1fa 100644
--- a/pywikibot/config.py
+++ b/pywikibot/config.py
@@ -572,15 +572,18 @@
# ############# EXTERNAL SCRIPT PATH SETTINGS ##############
# Set your own script path to lookup for your script files.
#
-# Your private script path must be located inside the
-# framework folder, subfolders must be delimited by '.'.
-# every folder must contain an (empty) __init__.py file.
+# Your private script path is relative to your base directory.
+# Subfolders must be delimited by '.'. every folder must contain
+# an (empty) __init__.py file.
#
# The search order is
# 1. user_script_paths in the given order
# 2. scripts/userscripts
# 3. scripts
# 4. scripts/maintenance
+# 5. pywikibot/scripts
+#
+# 2. - 4. are available in directory mode only
#
# sample:
# user_script_paths = ['scripts.myscripts']
diff --git a/pywikibot/scripts/__init__.py b/pywikibot/scripts/__init__.py
new file mode 100644
index 0000000..5a69b88
--- /dev/null
+++ b/pywikibot/scripts/__init__.py
@@ -0,0 +1,6 @@
+"""Folder which holds framework scripts.
+
+When uploading pywikibot to pypi the pwb.py (wrapper script) is copied here.
+
+.. versionadded:: 7.0
+"""
diff --git a/scripts/version.py b/pywikibot/scripts/version.py
similarity index 96%
rename from scripts/version.py
rename to pywikibot/scripts/version.py
index 9a2cf3d..77faad0 100755
--- a/scripts/version.py
+++ b/pywikibot/scripts/version.py
@@ -1,5 +1,9 @@
#!/usr/bin/python
-"""Script to determine the Pywikibot version (tag, revision and
date)."""
+"""Script to determine the Pywikibot version (tag, revision and date).
+
+.. versionchanged:: 7.0
+ version script was moved to the framework scripts folder
+"""
#
# (C) Pywikibot team, 2007-2021
#
diff --git a/scripts/README.rst b/scripts/README.rst
index c61f5d9..c4bf53f 100644
--- a/scripts/README.rst
+++ b/scripts/README.rst
@@ -145,9 +145,6 @@
+------------------------+---------------------------------------------------------+
| upload.py | Upload an image to a wiki. |
+------------------------+---------------------------------------------------------+
- | version.py | Outputs Pywikibot's revision number, Python's
version |
- | | and OS used. |
- +------------------------+---------------------------------------------------------+
| watchlists.py | Allows access to the account's watchlist.
|
+------------------------+---------------------------------------------------------+
| weblinkchecker.py | Check if external links are still working. |
diff --git a/setup.py b/setup.py
index c11224f..9615a85 100644
--- a/setup.py
+++ b/setup.py
@@ -256,6 +256,11 @@
download_url=metadata.__download_url__,
test_suite='tests.collector',
tests_require=test_deps,
+ entry_points={
+ 'console_scripts': [
+ 'pwb = pywikibot.scripts.pwb:run',
+ ],
+ },
classifiers=[
'Development Status :: 5 - Production/Stable',
'Environment :: Console',
--
To view, visit
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/738576
To unsubscribe, or for help writing mail filters, visit
https://gerrit.wikimedia.org/r/settings
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Change-Id: I51160dc4df95b59bac98acf9f4e170232c4923a2
Gerrit-Change-Number: 738576
Gerrit-PatchSet: 3
Gerrit-Owner: Xqt <info(a)gno.de>
Gerrit-Reviewer: AbdealiJK <abdealikothari(a)gmail.com>
Gerrit-Reviewer: D3r1ck01 <xsavitar.wiki(a)aol.com>
Gerrit-Reviewer: Dvorapa <dvorapa(a)seznam.cz>
Gerrit-Reviewer: Xqt <info(a)gno.de>
Gerrit-Reviewer: Yuvipanda <yuvipanda(a)gmail.com>
Gerrit-Reviewer: jenkins-bot
Gerrit-MessageType: merged