warning about NumPy/TensorFlow version conflicts; kudos @CatChenal

.pre-commit-config.yaml

@@ -11,7 +11,6 @@ repos:
     -   id: check-builtin-literals
     -   id: check-executables-have-shebangs
     -   id: check-merge-conflict
-    -   id: check-yaml
     -   id: debug-statements
     -   id: detect-private-key
     -   id: no-commit-to-branch

README.md

@@ -14,7 +14,7 @@ Welcome to *graph-based data science*:
 The **kglab** library provides a simple abstraction layer in Python
 3.6+ for building knowledge graphs.
 
-> **SPECIAL REQUEST**:   
+> **SPECIAL REQUEST:**  
 > Which features would you like in an open source Python library for building knowledge graphs?  
 > Please add your suggestions through this survey:  
 > https://forms.gle/FMHgtmxHYWocprMn6  
@@ -77,6 +77,13 @@ graph libraries in Python:
 <https://derwen.ai/docs/kgl/tutorial/>
 
 
+> **WARNING when installing in an existing environment:**  
+> Installing a new package in an existing environment may reveal  
+> or create version conflicts. See the **kglab** requirements  
+> in `requirements.txt` before you do. For example, there are  
+> [known version conflicts](https://github.com/DerwenAI/kglab/issues/160) regarding NumPy (>= 1.19.4) and [TensorFlow 2+](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/pip_package/setup.py) (~-1.19.2)
+
+
 <details>
   <summary>Contributing Code</summary>
 
@@ -160,16 +167,17 @@ and to our contributors:
 [@ceteri](https://github.com/ceteri),
 [@dvsrepo](https://github.com/dvsrepo),
 [@Ankush-Chander](https://github.com/Ankush-Chander),
-[@gauravjaglan](https://github.com/gauravjaglan),
 [@louisguitton](https://github.com/louisguitton),
+[@gauravjaglan](https://github.com/gauravjaglan),
+[@CatChenal](https://github.com/CatChenal),
 [@jake-aft](https://github.com/jake-aft),
 [@dmoore247](https://github.com/dmoore247),
 plus general support from [Derwen, Inc.](https://derwen.ai/);
 the [Knowledge Graph Conference](https://www.knowledgegraph.tech/)
 and [Connected Data London](https://connected-data.london/);
 plus an even larger scope of [use cases](https://derwen.ai/docs/kgl/use_case/)
 represented by their communities;
-[KFocus](https://kfocus.org/),
+[Kubuntu Focus](https://kfocus.org/),
 the [NVidia RAPIDS team](https://rapids.ai/),
 [Gradient Flow](https://gradientflow.com/),
 and

changelog.txt

@@ -1,5 +1,15 @@
 # `kglab` changelog
 
+## 0.3.1
+
+2021-04-??
+
+  * add multifile support for `load_jsonld()`; kudos @Ankush-Chander
+  * warning about NumPy/TensorFlow version conflicts; kudos @CatChenal
+  * roll back NumPy requirement to >= 1.19.2
+  * documenting notes about how to handle "PEP 517" errors
+
+
 ## 0.3.0
 
 2021-04-23

docs/ack.md

@@ -8,8 +8,9 @@ Many thanks to our open source [sponsors](https://github.com/sponsors/ceteri);
 and to our contributors:
 [@dvsrepo](https://github.com/dvsrepo),
 [@Ankush-Chander](https://github.com/Ankush-Chander),
-[@gauravjaglan](https://github.com/gauravjaglan),
 [@louisguitton](https://github.com/louisguitton),
+[@gauravjaglan](https://github.com/gauravjaglan),
+[@CatChenal](https://github.com/CatChenal),
 [@jake-aft](https://github.com/jake-aft),
 [@dmoore247](https://github.com/dmoore247);
 plus general support from [Derwen, Inc.](https://derwen.ai/);
@@ -119,6 +120,9 @@ See also:
   * [PheKnowLator](https://github.com/callahantiff/PheKnowLator)
     * *pro:* quite similar to **kglab** in intent; well-written code; sophisticated, opinionate build of biomedical KGs
     * *con:* less integration with data science tools or distributed systems
+  * [GraphScope](https://github.com/alibaba/GraphScope)
+    * *pro:* loads of features, excellent support, broad adoption
+    * *con:* less of a *library* more of a *client/server* architecture; aims to reinvent instead of integrating
   * [LynxKite](https://lynxkite.com/)
     * *pro:* loads of features, lots of adoption
     * *con:* complex tech stack, combines Py/Java/Go; AGPL less-than-business-friendly for production apps

docs/build.md

@@ -14,6 +14,7 @@ simply install based on the instructions in
 
 To set up the build environment locally:
 ```
+python3 -m pip install -U pip setuptools wheel
 python3 -m pip install -r requirements-dev.txt
 ```
 
@@ -139,7 +140,16 @@ tar cvzf kgl.tgz site/
 
 ## Package Release
 
-To update the [release on PyPi](https://pypi.org/project/kglab/):
+First, verify that `setup.py` will run correctly for the package
+release process:
+
+```
+python3 -m pip install -e .
+python3 ./test.py
+python3 -m pip uninstall kglab
+```
+
+Then update the [release on PyPi](https://pypi.org/project/kglab/):
 ```
 ./bin/push_pypi.sh
 ```

docs/depend.md

@@ -4,6 +4,8 @@
 
 The **kglab** package requires [Python 3.6+](https://www.python.org/downloads/).
 
+## Base Support
+
 Package dependencies as defined in
 [`requirements.txt`](https://github.com/DerwenAI/kglab/blob/main/requirements.txt)
 include:
@@ -16,7 +18,7 @@ include:
 - [icecream](https://github.com/gruns/icecream)
 - [matplotlib](https://matplotlib.org/)
 - [NetworkX](https://networkx.org/)
-- [NumPy](https://numpy.org/)
+- [NumPy](https://numpy.org/)[^2]
 - [OWL-RL](https://owl-rl.readthedocs.io/)
 - [pandas](https://pandas.pydata.org/)
 - [pslpython](https://psl.linqs.org/)
@@ -44,9 +46,12 @@ Additional package dependencies are required for GPU support through
 - [cuDF](https://docs.rapids.ai/api/cudf/stable/api.html)
 - [cuGraph](https://docs.rapids.ai/api/cugraph/stable/api.html)
 
-These require use of `conda` and we strongly recommend that you
-determine the correct configuration via the 
-[release selector](https://rapids.ai/start.html#get-rapids).
+These require use of `conda` as a base, and we strongly recommend
+using the [release selector](https://rapids.ai/start.html#get-rapids).
+to determine the correct configuration
+
+Then use `pip` to install the other **kglab** dependencies atop
+that base `conda` environment.
 
 
 ## iGraph support
@@ -61,4 +66,53 @@ Instead you'll need to install the following packages separately:
 - [python-igraph](https://igraph.org/python/)
 
 
+## Troubleshooting
+
+### PEP 517
+
+If you are using `pip` you may run into the dreaded
+[`PEP 517`](https://www.python.org/dev/peps/pep-0517/)
+errors when installing libraries.
+
+Problems tend to be encountered with particular dependencies such as
+`statsmodels`, `multidict`, `yarl`, and so on, with error messages
+similar to:
+
+> ERROR: Could not build wheels for **foobar** which use PEP 517  
+> and cannot be installed directly
+
+To be clear, this is partly due to the fact that both Windows and
+macOS cut corners on their attempts to balance being both "consumer
+products" and actual operating systems.
+Consequently their compiler environments can became gnarled messes –
+especially when you must work with a wide range of machine learning
+libraries, which tend to stress this point.
+
+To be blunt, using Linux (e.g., Ubuntu, etc.) helps if you're serious
+about software engineering.
+
+The best advice we can give to help troubleshoot this constellation 
+of errors is that `PEP 517` does not play well with Python
+[virtual environments](https://docs.python.org/3/tutorial/venv.html).
+If you get stuck with installation errors, find a way around using a
+virtual environment.
+
+You can also try to use the following approach to pre-load the
+troublesome dependencies, although YMMV:
+
+```
+pip install statsmodels  --no-binary :all:
+```
+
+This is be no means a simple matter to resolve.
+For more details about root issues encountered when building Python
+packages, the following discussions are highly recommended:
+
+  * <https://twitter.com/wesmckinn/status/1148350953793490944>
+  * <https://discuss.python.org/t/pep-517-and-projects-that-cant-install-via-wheels/791>
+  * <https://labs.quansight.org/blog/2021/01/python-packaging-brainstorm/>
+
+
 [^1]: You may need to [install extra dependencies](https://filesystem-spec.readthedocs.io/en/latest/index.html?highlight=extra#installation) for `fsspec` since not all included filesystems are usable by default. Support for Amazon S3 and Google GCS are installed by default. See the `extras_require` dict in <https://github.com/intake/filesystem_spec/blob/master/setup.py>
+
+[^2]: There are [known version conflicts](https://github.com/DerwenAI/kglab/issues/160) regarding NumPy (>= 1.19.4) and [TensorFlow 2+](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/pip_package/setup.py) (~-1.19.2)