Skip to content

[IDE] Configuring PyCharm

Jump to bottom
James Whale edited this page May 11, 2022 · 3 revisions

LibreNMS Handler was developed using PyCharm as an Integrated Development Environment (IDE). As the project was developed with publishing to PyPI in mind, the file structure may not be as familiar as people are used to. This page intends to help developers who use PyCharm as an IDE get set up and ready for contribution. It will assume minimal knowledge from the user, as to include all audiences (If I assume too much somehow, let me know via an issue and I'll add in the additional information).

Prerequisites

To ensure everyone is on the same page, all tools used during development will be noted here with relevant installation instructions.

Pipenv

This project was designed using Pipenv instead of Pip. Most systems that have Python installed also include Pip as the package manager, however Pipenv is still not as popular and as such not included. With the assumption of Pip installed, the official documents state the installation instructions of pip install pipenv. Using the instruction verbatim instead of including the --user flag will install the package for all users on the system.

Creating the Project

To begin contributing, PyCharm must be set up to enable you to work on the most recent code and make additions. The steps required to get going are outlined below, but WARNING: instructions change over time, so this may not be 100% accurate at the time of reading. NOTE: If PyCharm does not start on this screen, go to File>Close Project to exit your currently opened project and return to the next screen.

  1. Click: Get from VCS (top right)
  2. Enter: https://github.com/WhaleJ84/librenms_handler.git into the URL field in the right-hand side column
  3. Click: Clone (bottom right)
  4. When PyCharm informs of detected project dependencies for Pipenv, click OK

Right now, if you tried to recreate the README example and import from librenms_handler.devices import Devices, your script will throw an error: 'Unresolved reference 'librenms_handler''. This is because of a context miss-match; the PyPI module sees content from within src/ but PyCharm sees content from within librenms_handler/ (your project root, not src/librenms_handler). You can configure your IDE to follow suit by doing the following:

  1. Right-click src > Mark Directory As > Sources Root

Once your IDE re-indexes the files, the error should disappear.

  1. Continue following the README example with the Devices endpoint, and use the devices.list_devices() call

NOTE: make sure to replace the URL and token with your relevant information.

  1. Click: Add Configuration... (top right)
  2. Click: Add new run configuration...
  3. Click: Python
  4. Click the folder icon to the right-hand side of Script path
  5. Under your project directory, select your Python script and click OK
  6. Click: OK (bottom right)

This creates a configuration that runs the test script for us. You can run it by doing the following:

  1. Click: Run '$SCRIPT' (top right, green play icon)

This will open a Run pane at the bottom of your IDE and display the output.

With these steps, you should be set to start playing with the code and testing it locally.

Clone this wiki locally