Merge pull request #207 from blurstudio/site_config

Add site customization of _common_members

Author: mottosso

Qt.py

@@ -43,7 +43,7 @@
 import shutil
 import importlib
 
-__version__ = "1.0.0.b5"
+__version__ = "1.0.0.b6"
 
 # Enable support for `from Qt import *`
 __all__ = []
@@ -431,6 +431,7 @@
         "QMetaMethod",
         "QMetaObject",
         "QMetaProperty",
+        "QMetaType",
         "QMimeData",
         "QModelIndex",
         "QMutex",
@@ -598,6 +599,18 @@
 }
 
 
+def _apply_site_config():
+    try:
+        import QtSiteConfig
+    except ImportError:
+        # If no QtSiteConfig module found, no modifications
+        # to _common_members are needed.
+        pass
+    else:
+        # Update _common_members with any changes made by QtSiteConfig
+        QtSiteConfig.update_members(_common_members)
+
+
 def _new_module(name):
     return types.ModuleType(__name__ + "." + name)
 
@@ -1041,6 +1054,9 @@ def _install():
 
     _log("Order: '%s'" % "', '".join(order))
 
+    # Allow site-level customization of the available modules.
+    _apply_site_config()
+
     found_binding = False
     for name in order:
         _log("Trying %s" % name)

README.md

@@ -35,6 +35,14 @@ Qt.py enables you to write software that runs on any of the 4 supported bindings
 - [Install](#install)
 - [Usage](#usage)
 - [Documentation](#documentation)
+  - [Environment Variables](#environment-variables)
+  - [Subset](#subset)
+  - [Branch binding-specific code](#branch-binding-specific-code)
+  - [Override preferred choice](#override-preferred-choice)
+  - [QtSiteConfig.py](#qtsiteconfigpy)
+  - [Compile Qt Designer files](#compile-qt-designer-files)
+  - [Loading Qt Designer files](#loading-qt-designer-files)
+  - [sip API v2](#sip-api-v2)
 - [Rules](#rules)
 - [How it works](#how-it-works)
 - [Known problems](#known-problems)
@@ -193,6 +201,45 @@ Using the OS path separator (`os.pathsep`) which is `:` on Unix systems and `;`
 
 <br>
 
+##### QtSiteConfig.py
+
+Add or remove members from Qt.py at run-time.
+
+-  [Examples](/examples/QtSiteConfig)
+
+<br>
+
+If you need to expose a module that isn't included in Qt.py by default or wish to remove something from being exposed in Qt.py you can do so by creating a `QtSiteConfig.py` module and making it available to Python.
+
+1. Create a new file `QtSiteConfig.py`
+2. Implement `update_members`
+3. Expose to Python
+
+```python
+# QtSiteConfig.py
+def update_members(members):
+	"""Called by Qt.py at run-time to modify the modules it makes available.
+
+    Arguments:
+        members (dict): The members considered by Qt.py
+
+    """
+
+    members.pop("QtCore")
+```
+
+Finally, expose the module to Python.
+
+```bash
+$ set PYTHONPATH=/path/to
+$ python -c "import Qt.QtCore"
+ImportError: No module named Qt.QtCore
+```
+
+> Linux and MacOS users, replace `set` with `export`
+
+<br>
+
 ##### Compile Qt Designer files
 
 > WARNING - ALPHA FUNCTIONALITY<br>
@@ -406,15 +453,15 @@ if binding("PyQt4"):
 Below are some of the conventions that used throughout the Qt.py module and tests.
 
 - **Etiquette: PEP8**
- 	- All code is written in PEP8. It is recommended you use a linter as you work, flake8 and pylinter are both good options. Anaconda if using Sublime is another good option.
+    - All code is written in PEP8. It is recommended you use a linter as you work, flake8 and pylinter are both good options. Anaconda if using Sublime is another good option.
 - **Etiquette: Double quotes**
     - " = yes, ' = no.
 - **Etiquette: Napoleon docstrings**
-	- Any docstrings are made in Google Napoleon format. See [Napoleon](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for details.
+    - Any docstrings are made in Google Napoleon format. See [Napoleon](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for details.
 - **Etiquette: Semantic Versioning**
-	- This project follows [semantic versioning](http://semver.org).
+    - This project follows [semantic versioning](http://semver.org).
 - **Etiquette: Underscore means private**
-	- Anything prefixed with an underscore means that it is internal to Qt.py and not for public consumption.
+    - Anything prefixed with an underscore means that it is internal to Qt.py and not for public consumption.
 
 **Running tests**
 

examples/QtSiteConfig/QtSiteConfig.py

@@ -0,0 +1,14 @@
+# Contrived example used for unit testing. This makes the QtCore module
+# not accessible. I chose this so it can be tested everywhere, for a more
+# realistic example see the README
+
+
+def update_members(members):
+    """This function is called by Qt.py to modify the modules it exposes.
+
+    Arguments:
+        members (dict): The members considered by Qt.py
+
+    """
+
+    members.pop("QtCore")

examples/QtSiteConfig/README.md

@@ -0,0 +1,100 @@
+## `QtSiteConfig` example
+
+This example illustrates how to make a QtSiteConfig module and how it affects Qt.py at run-time.
+
+<br>
+
+**Usage**
+
+```bash
+$ cd to/this/directory
+$ python main.py
+# Qt.QtCore was successfully removed by QSideConfig.py
+```
+
+Because `QtSiteConfig.py` is in the current working directory, it is available to import by Python. If running from a different directory, then you can append this directory to your `PYTHONPATH`
+
+```bash
+$ set PYTHONPATH=path/to/QtSiteConfig/
+$ python main.py
+# Qt.QtCore was successfully removed by QSideConfig.py
+```
+
+> Linux and MacOS users: Replace `set` with `export`
+
+<br>
+
+**Advanced example**
+
+If you need to  you can also add modules that are not in the standard Qt.py.
+
+```python
+def update_members_example(members):
+    """An example of adding QJsonDocument to QtCore and the Qsci.
+    
+    Remove "_example" from the function name to use this example.
+
+    Arguments:
+        members (dict): The default list of members in Qt.py.
+            Update this dict with any modifications needed.
+
+    """
+
+    # Include QJsonDocument module
+    members["QtCore"].append("QJsonDocument")
+
+    # Include Qsci module for scintilla lexer support.
+    members["Qsci"] = [
+        "QsciAPIs",
+        "QsciAbstractAPIs",
+        "QsciCommand",
+        "QsciCommandSet",
+        "QsciDocument",
+        "QsciLexer",
+        "QsciLexerAVS",
+        "QsciLexerBash",
+        "QsciLexerBatch",
+        "QsciLexerCMake",
+        "QsciLexerCPP",
+        "QsciLexerCSS",
+        "QsciLexerCSharp",
+        "QsciLexerCoffeeScript",
+        "QsciLexerCustom",
+        "QsciLexerD",
+        "QsciLexerDiff",
+        "QsciLexerFortran",
+        "QsciLexerFortran77",
+        "QsciLexerHTML",
+        "QsciLexerIDL",
+        "QsciLexerJSON",
+        "QsciLexerJava",
+        "QsciLexerJavaScript",
+        "QsciLexerLua",
+        "QsciLexerMakefile",
+        "QsciLexerMarkdown",
+        "QsciLexerMatlab",
+        "QsciLexerOctave",
+        "QsciLexerPO",
+        "QsciLexerPOV",
+        "QsciLexerPascal",
+        "QsciLexerPerl",
+        "QsciLexerPostScript",
+        "QsciLexerProperties",
+        "QsciLexerPython",
+        "QsciLexerRuby",
+        "QsciLexerSQL",
+        "QsciLexerSpice",
+        "QsciLexerTCL",
+        "QsciLexerTeX",
+        "QsciLexerVHDL",
+        "QsciLexerVerilog",
+        "QsciLexerXML",
+        "QsciLexerYAML",
+        "QsciMacro",
+        "QsciPrinter",
+        "QsciScintilla",
+        "QsciScintillaBase",
+        "QsciStyle",
+        "QsciStyledText",
+    ]
+```

examples/QtSiteConfig/__init__.py

@@ -0,0 +1,30 @@
+"""Example of QtSideConfig module used to modify exposed members of Qt.py"""
+
+import os
+import sys
+
+
+def test():
+    """QtCore is taken out of Qt.py via QSiteConfig.py"""
+
+    # Expose this directory, and therefore QtSiteConfig, to Python
+    sys.path.insert(0, os.path.dirname(__file__))
+
+    try:
+        from Qt import QtCore
+
+    except ImportError:
+        print("Qt.QtCore was successfully removed by QSideConfig.py")
+
+    else:
+        raise ImportError(
+            "Qt.QtCore was importable, update_members was not "
+            "applied correctly."
+        )
+
+        # Suppress 'Qt.QtCore' imported but unused warning
+        QtCore
+
+
+if __name__ == '__main__':
+    test()

examples/QtSiteConfig/main.py

@@ -12,4 +12,5 @@ If you wish to contribute, make a pull request. Please put your example files in
 
 #### List of examples   
 
-* [`loadUi`](https://github.com/mottosso/Qt.py/blob/master/examples/loadUi/README.md) - add base instance argument
+* [`loadUi`](/examples/loadUi/README.md) - add base instance argument
+* [`QtSiteConfig`](/examples/QtSiteConfig/README.md) - expose additional Qt modules and classes