Package: dss.netapi-python
Table of ContentsIntroductionInstallation and configurationUsage and examplesDevelopmentIntroductionGraphs or networks are everywhere and are of great interest for researchers.
Examples of interesting sources of social networks are:Social Media such as Facebook, Twitter provide networks of "friends".Crawlers provide networks of documents or hostsCollections of research papers can be regarded as interaction networks of
individuals or organisationsThe NetAPI aims to provide a framework to enables the use of
project-specific data-structures and a normalized view of the requested graphs.
Thus, this approach allows for specialization of researchers:
researches providing a specific implementation of a NetAPI-Server
using the raw data and other researchers accessing this data for answering
specific research questions.TheNetAPI-Serveris a server component with endpoints providing access to such -
possibly dynamic - graphs. It provides the possibility to answer queries
using a specific QueryEngine.In a NetAPI-Server implementations ofGraph Sourcesprovide events to create graphs.
Typically a project requires a specific implementation which is responsible to create
Events building a graph from the raw data.ANetAPI-Clientimplementation enables researches to access the data of
a NetAPI-Server in a standardized way - independent of the actual raw data.
Thus networks of social media and crawled data can be accessed in the same manner.This packageprovides a Python3 client for accessing NetAPI-Server which simplifies
creating and sending queries to the NetAPI and to transform the responses to a graph.
This can then be easily be used for further processes in Python.This architecture is depicted in the following image:---------------          -------------------
| QueryEngine 	|  <==>  | dss.netapi-client |
 ---------------          -------------------
  NetAPI-Server              NetAPI-Client
   e.g. QKnowInstallation and configurationThedss-netapi-pythonpackage has to be installed via pip -
the package installer for Python. Two variants can be installed:
a published stable version or the current development version.Normally, it is preferable to use the published stable version in a
separatevirtual environmentin your projects source folder:py -m venv .venv # creates the environment
.venv\Scripts\Activate.bat # might also be .venv\bin\Activate.batMore info on this topic can be found here:https://docs.python.org/3/library/venv.htmlThe current stable version can be installed via a pip-command:py -m pip install dss-netapi-python --userIf you already have a installed version ofdss-netapi-pythonin your local environment it can be updated using the following pip-command:py -m pip install --upgrade dss-netapi-pythonConfigurationThe NetAPIClient makes requests to another server. Users have to
authenticate to the server to allow authorization to the requested resources.Clients of the NetAPI can be configured via the file~/.netapi/config(~ is the usual abbreviation of the current user's home directory).
An example of such a configuration file can be found below:[default] #<1>
host=https://qknow-dc.dev.plattform-gmbh.de #<2>
token=atoken #<3>

[qknow-live] #<4>
host=https://qknow-dc.live.plattform-gmbh.de
token=anothertokenA profiledefaultis definedThe URL of the host where the NetAPI-Server residesAn authentication token.A second profileqknow-liveis definedThese profiles can be used thto construct a suitable instance
for the communication with the server.
This will be demonstrated in the following source code examples.Usage and examplesThis section makes examples how to use thedss-netapi-pythonpackage.Example 1: Reading a graphDemonstrates the most basic form of interaction with the NetAPI: reading a graph.from netapi import * #<1>

client = NetAPIClient.fromConfig("default") #<2>

req = GraphQueryRequest()\
      .setSource("InputStreamReplayToSource", "MiniGraph.dgs") #<3>
res = client.query(req) #<4>

graphModel = res.getGraphModel() #<5>
graph = graphModel.asMultiDiGraph() #<6>

print(graph)Imports the netapi-moduleCreates a new instance of the NetAPIClient from the profile "default" using the configuration file.Creates a request using the a InputStreamReplayToSource and a well-known file (actually a file for test-cases)Sends the query and receives the response objectExtracts the generic graph modelCreates a networkx-view of the graph model. In this case a directed graph allowing for multiple edges between nodes.Example 2: TaggingTODOExample 3: Aggregating nodesTODOExample 4: Filter nodes and edgesWenn man Prädikate definiert, wird "true" für Java klein geschrieben.
Nicht wie bei Python groß.
z.B setSelection(Selection().setNodePredicate("attributes.egoA=true"))DevelopingSources:https://docs.python-guide.org/writing/structure/https://docs.python.org/3/library/unittest.htmlInstalling the development versionIn rare cases you might want to use the development version.
The development version can be installed as a regular pip-module.
The source code can be accessed via a git repository.
If you have the necessary user authentication, it can be cloned like this:git clone https://gitea.plattform-gmbh.de/PlattformGmbH/datacollector.gitAfter cloning the git repository the pip-module actually has to be installed:cd datacollector/netapi-python
py -m pip install -e .When changing / updating the source code it is automatically reflected in
the pip-module. Thus a simplegit pulloften suffices to make sure that the newest development version is used.IMPORTANT:Sometimes the dependencies of the NetAPI are updated. To make sure that also
all dependencies are updated as well the install command from above has to be
executed again.Running TestCasesCurently TestCases can only be run successfully, if you have an running local
NetAPI-Server:cd datacollector
./mvnw spring-boot:runTestCases have to be run in the terminal in the workingdir "netapi-python/tests".Runningonetest in a class:py -m unittest -v SimpleTestGraphTestCase -k test_2Runningalltests in a class:py -m unittest -v SimpleTestGraphTestCaseRunningallknown tests (a.k.a TestSuite):py -m unittest -v AllTestsPublish Package to a Package-Manager (PIP, Gitea, ..)Check current version:py -m setuptools_scmInstall/Update build-toolspy -m pip install --upgrade pip build twineGenerate distribution-archives (in folder dist)rm dist/*; py -m buildUpload distribution-archives. Please make sure, that therepositoryis configured in you local~\.pypircfile.py -m twine upload --repository [REPOSITORY] dist/*Possible repositories are gitea, testpypi or pypi.Testing installation of pip-module inseparatevirtual environment:pip install --extra-index-url https://test.pypi.org/simple/ dss-netapi-pythonSources:https://packaging.python.org/en/latest/tutorials/packaging-projects/https://docs.gitea.io/en-us/usage/packages/pypi/