Document usage of pico as a module. (#200)

Author: kysrpex

docs/source/api_ref.md

@@ -84,4 +84,10 @@ This document is for developers and/or advanced users of OSP-core, it contains a
 .. automodule:: osp.core.utils
    :imported-members:
    :members:
-```
+```
+
+### pico
+```{eval-rst}
+.. automodule:: osp.core.pico
+   :members: install, uninstall, packages, namespaces
+```

docs/source/utils.md

@@ -1,27 +1,34 @@
 # Utilities
 In this section we will compile a list of useful utility functions, tools and examples of their usage.
-These functions are part of OSP-core and are used as an extension of the 
-[main API](./detailed_design.md#cuds-api).
+These functions are part of OSP-core and are used as an extension of the [main API](./detailed_design.md#cuds-api).
 
-## Pico Installs Cuds Ontologies
+## pico (Pico Installs Cuds Ontologies)
 Our tool for installing ontologies is called `pico`.
 It is a recursive acronym that stands for _Pico Installs Cuds Ontologies_.
 
-There are 3 main things that can be done with pico:
+There are 3 main operations that can be done with pico:
 - Install ontologies.
 - List the installed ontologies.
 - Remove installed ontologies.
 
-There are different possible levels of log available, and they can be set via
+`pico` can be used both from the [command-line](utils.md#using-pico-from-the-command-line)
+and [as a Python module within the Python shell](utils.md#using-pico-as-a-python-module).
+
+### Using pico from the command line
+
+There are different possible logging levels available, and they can be set via
 `--log-level <ERROR|WARNING|INFO|DEBUG>`. The default value is `INFO`.
 
-### Pico installs
-_Usage:_ `pico install <path/to/ontology.yml>|city|cuba`
+#### pico installs
+_Usage:_ 
+- `pico install <path/to/ontology_yml_file.yml>`
+- `pico install <path/to/ontology_yml_file1.yml> <path/to/ontology_yml_file2.yml> ...`
+- `pico install city foaf emmo dcat2` (the installation of these specific 
+  well-known ontologies is available via this shortcut)
 
 _Behaviour:_ 
-- The ontology file is parsed, and the entities mapped to python objects.
-- The python classes can be imported via their namespace
-  `from osp.core.namespaces import namespace`
+- The ontology file is parsed, and the entities mapped to Python objects.
+- The Python objects can be imported via their namespace `from osp.core.namespaces import namespace`.
 
 _Example:_
 ```console
@@ -33,12 +40,13 @@ INFO [osp.core.ontology.parser]: Loaded 367 ontology triples in total
 INFO [osp.core.ontology.installation]: Installation successful
 ```
 
-### Pico lists
+#### pico lists
 _Usage:_ `pico list`
 
 _Behaviour:_ 
 - The installed namespaces and packages are printed out. A package can be
-uninstalled and can contain many namespaces. A namespace can be imported in code.
+uninstalled and can contain many namespaces. A namespace can be imported 
+  within the Python shell.
 
 _Example:_
 ```console
@@ -56,34 +64,26 @@ Namespaces:
         - city
 ```
 
-### Pico uninstalls
-_Usage:_ `pico uninstall <package>|all`.
-Note that to select all the packages, `all` must be quoted.
+#### pico uninstalls
+_Usage:_ 
+- `pico uninstall <package>`
+- `pico uninstall all`
 
 _Behaviour:_ 
-- All installed packages / namespaces are uninstalled.
-- All namespaces except the uninstalled ones are re-installed.
+- The specified packages are uninstalled.
+- All packages except the uninstalled ones are re-installed.
 
 _Example:_
 ```console
+(venv) user@PC:~$ pico uninstall city
 INFO [osp.core.ontology.installation]: Will install the following namespaces: ['qe']
 INFO [osp.core.ontology.yml.yml_parser]: Parsing YAML ontology file /home/<username>/.osp_ontologies/qe.yml
 INFO [osp.core.ontology.yml.yml_parser]: You can now use `from osp.core.namespaces import qe`.
 INFO [osp.core.ontology.parser]: Loaded 205 ontology triples in total
 INFO [osp.core.ontology.installation]: Uninstallation successful
 ```
 
-### Ontology installation folder
-
-The installed ontologies are stored in the directory `~/.osp-ontologies` by 
-default. On Windows, `~` usually refers to the path 
-`C:\Users\<my username>`.
-
-The installation directory can be changed by setting the
-environment variable `OSP_ONTOLOGIES_DIR`. Such action would move it to 
-`$OSP_ONTOLOGIES_DIR/.osp-ontologies`.
-
-### Conflicts with other "pico" installations
+#### Conflicts with other "pico" installations
 Some Operating Systems might have a pre-existing tool called _pico_.
 In most cases, the previous commands should work, but if any problem arises,
 you can use the following alternative:
@@ -97,6 +97,54 @@ For example:
 python -m osp.core.pico install city
 ```
 
+### Using pico as a Python module
+
+`pico` can also be used within the Python shell. In particular, four 
+functions are available to be imported from the `osp.core.pico` module,
+
+```python
+from osp.core.pico import install, namespaces, packages, uninstall
+```
+
+that cover the three main operations that pico is meant to perform: installing 
+ontologies (`install`), uninstalling ontologies (`uninstall`), and listing the 
+installed ontologies (`packages`, `namespaces`).
+
+Each function is used in a similar way to its command-line counterpart.
+
+- `install`: accepts _one or more_ positional arguments of string
+type, which can be either paths to `yml` ontology installation files or 
+names of ontologies that can be installed via this shortcut. It is meant to 
+clone the 
+[behavior of its command-line counterpart](https://simphony.readthedocs.io/en/latest/utils.html#pico-installs).
+
+- `uninstall`: accepts _one or more_ positional arguments of string type, 
+  which must be names of already installed ontology packages. It also 
+  clones the [behavior of its command-line counterpart](https://simphony.readthedocs.io/en/latest/utils.html#pico-uninstalls).
+
+- `packages`: accepts no arguments and returns an [iterator](https://wiki.python.org/moin/Iterator) 
+   over the names of the installed packages.
+
+- `namespaces`: accepts no arguments and returns an iterator yielding one 
+  [`OntologyNamespace` object](https://simphony.readthedocs.io/en/latest/api_ref.html#osp.core.ontology.namespace.OntologyNamespace) for each installed namespace.
+
+Usage examples:
+
+- `install('city', 'path/to/ontology_yml_file.yml')`, `install('foaf', 'dcat2')`
+- `uninstall('city', 'foaf')`
+- `print(list(packages()))`
+- `print(list(namespaces()))`
+
+### Ontology installation folder
+
+The installed ontologies are stored in the directory `~/.osp-ontologies` by 
+default. On Windows, `~` usually refers to the path 
+`C:\Users\<my username>`.
+
+The installation directory can be changed by setting the
+environment variable `OSP_ONTOLOGIES_DIR`. Such action would move it to 
+`$OSP_ONTOLOGIES_DIR/.osp-ontologies`.
+
 ## Tips and tricks
 The following are some utility functions and shortcuts for working with cuds.
 For those that are present in the util package, the import is `from osp.core import utils`.

requirements.txt

@@ -11,4 +11,3 @@ sphinx-autobuild==2021.3.14
 sphinx-panels==0.5.2
 jinja2==2.11.3
 markupsafe==2.0.1
-