Getting started with Packagr

Getting started with Packagr

What is Packagr?

Packagr is a secure and private cloud hosted package and dependency manager for Python. It allows you to securely store, distribute, collaborate on and deploy your Python code wherever it is needed.

Packagr integrates seamlessly with your existing CI/CD workflows and allows you to collaborate with very large teams of developers, with generous file storage limits.

Signing up for a Packagr account

In order to use Packagr, you first first sign up for an account on our homepage, by clicking on the purple Sign up now button

landing page screenshot

You’ll be prompted to enter your email address and password. Do so, then click the Register button

signup-form

You’ll then need to verify your email address - you’ll be emailed a 6 digit numeric token at the email address you entered. Enter this number into the Token field to verify your account. If you don’t recveive an email, remember to check your spam folder. The token generated is valid for an hour. If you have issues verifying your email address, please contact us at info@packagr.app.

Enter verification token

Once you’ve successfully verified your email address, you’ll be able to login to your Packagr account. When you first login you’ll be taken to your package list, which will be empty for now:

Package list in Packagr

Your repository URL and Hash ID

When you create a Packagr account you will be assigned a unique repository URL and a unique Hash ID. You will need these pieces of data at various times while you are using Packagr. You can retrieve these pieces of information from the Packagr interface logging in and clicking on Create new package. Your repository URL and Hash ID will be displayed at the top of the screen, like so:

Finding your repository URL

It will always be in this same format:

Repository URL: https://api.packagr.app/<my-hash-id>/
Hash ID: <my-hash-id>

You should make a note of these values for future reference, although they will always be displayed here for your information

Uploading your packages to Packagr

Important note

When you first create a Packagr account, you’ll be signed up for the Free tier. In the Free tier, you cannot create any private packages - every package that you upload to Packagr will be marked as public, meaning that anyone with your repository URL will be able to download and install your packages. You should NOT upload any packages that you want to keep private until you have upgraded your account via the accounts page. When you have a paid account, any packages you create will be marked as private, and can only be downloaded by those with access to that specific package. See Managing access to Packages for more information

Creating a Package

Packagr support Python packages generated by tools such as distutils or setuptools. Packagr supports both sdist (tarball) and wheel packages.

As an example, let’s build a very simple hello-world Python, package it, upload it to Packagr, and install it in a different environment using pip to round trip the whole process

Let’s start by creating the following folder simple structure:

helloworld/
    hello.py
setup.py

Open the file hello.py, and add the following code

def hello(*args, **kwargs):
    return 'Hello, World!'

In the file setup.py, add the following:

from setuptools import setup

setup(
  name="hello",
  packages=["helloworld"],
  version="0.1.0",
  entry_points={
    'console_scripts': [
      'hello=helloworld:hello.hello',
    ]
  }
)

We now have some basic code (our hello.py file), and a setup configuration that tells setuptools how to install it. We’ve specified a package name, hello, a version, 0.1.0, told setuptools to include the helloworld directory and added a console_script that will run our Python code when we type the world hello into a terminal window.

We are now ready to package it. Let’s create wheel and sdist format packages from it. We’ll need to install the wheel package first:

pip install wheel

We can then build our package with the following commands:

python setup.py sdist bdist_wheel

This should look something like the following:

You should now see that a few new folders have been added to our project:

build/
dist/
  hello-0.1.0.tar.gz
  hello-0.1.0-py3-none-any.whl
hello.egg-info/
...

The dist folder contains our new packages, ready to be uploaded to Packagr

Uploading the package to Packagr

We can now upload our package to Packagr using twine. Let’s start by installing twine using pip

pip install twine

We can now upload our package to Packagr using the following command (don’t forget to insert your own repository URL here):

twine upload  --repository-url https://api.packagr.app/<my-hash-id>/ dist/*

You’ll be prompted for credentials at this stage - enter the email address and password that you signed up for Packagr with. If all goes well, it should look something like this:

If your upload succeeds, you should also be able to see your newly created package in the Packagr interface:

Package uploaded to Packagr

Important note

twine is not the only way to upload packages to Packagr - in fact, there are several other more covenient ways of doing so. For all the supported options for package uploads, please refer to uploading packages to Packagr

Installing a package from Packagr

We can now use pip to install our package. We’ll need to pass the --extra-index-url parameter when doing so, as follows. Once again, you’ll need to replace the repository URL shown here with your own. Note that you can find this installation command by going into the package details in the Packagr app, and clicking on the installation tab.

pip install hello --extra-index-url https://api.packagr.app/<my-hash-id>/

If the package you are trying to install is marked as private, then you will be asked to provide your credentials in order to install the package. If your package is public (the only option for free users), then no credentials will be asked for.

Important note

In order to point pip at your Packagr repository, you can either use the --extra-index-url or simlpy the --index-url switch. In the case of our simple hello-world example, providing the --index-url switch to install the package would have achieved the same result as the command above. However, if your package has dependencies on our packages in the public PyPI repository, then your installation would fail as pip can only install packages from multiple locations if the --extra-index-url switch is used. It is therefore generally better to use --extra-index-url instead of --index-url, but keep in mind that if your packages have the same name as a public package on PyPI, then you may see undesirable behaviour.