Download scripts for the CSD Python API from the CSD GitHub repository

The CSD GitHub repository is the place to download, edit, and share python scripts to perform chemistry tasks and analyses using the CSD Python API. Here we’ll explain how to access it.

Find scripts for the CSD Python API

You can now download scripts to use with the CSD Python API from our new CSD GitHub repository.

This replaces the old CSD Python API forum, making it easier to merge changes and manage the scripts.

 

>> Access the CSD GitHub repository here to download, edit and submit scripts for the CSD Python API. <<

 

Jump to:

 

What can you do with the CSD Python API?

The possibilities are almost endless. The CSD Python API gives you programmatic access to the Cambridge Structural Database (CSD) as well as features in the CSD software such as Mercury, GOLD, and CSD-CrossMiner.

To give a few examples:

 

How to use the CSD Python API

Find the documentation for the CSD Python API here. This includes release and installation notes, examples and tips.

If you're getting started with the CSD Python API, try our on-demand 90-minute module here: Programmatic access to the CSD 101 — CSD Python API.

You do need knowledge of Python to get started. If you're learning Python, realpython.com is a great resource to get started.

 

How to use the CSD GitHub repo

Each script in the repository comes with an associated ReadMe file that contains a summary of what the script does, how to use it, any dependencies, and any licences required.

For those familiar with GitHub, we suggest creating a fork of the repository so you can keep up to date with any changes. If you’re new to GitHub, there are some great resources online to get started.

If you have any questions about submitting a script or downloading and using scripts, contact us on support@ccdc.cam.ac.uk.

 

How to download CSD Python API scripts from the CSD GitHub repo

To download 1 set of scripts from the CSD GitHub repo, follow the instructions here.

 

If you just want quick access to the scripts in one click, you can download a snapshot of the repository to a zip file that contains all the scripts.

To download and run one script in the CSD Python API:

    1. Go to the CSD GitHub Repo.
    2. Click on the green “Code” button
    3. Download ZIP Download the ZIP file from GitHub
    4. Unpack the compressed file.
    5. Navigate to your script of choice (each script contains a ReadMe describing what it does and how to use it)
    6. Run the script using the CSD Python API conda environment (or your own!).
1    "\CCDC\Python_API_2022\miniconda\Scripts\activate.bat"
2 python script_example.py

 

How to submit scripts to the CSD GitHub repo

Its possible for you our user community to submit scripts. If you have a script you think others would find useful—please share it! You can also modify existing scripts, to add functionality or improve them.

We welcome python scripts to perform any tasks relating to the CSD, from the simple to complex. Some of our most popular scripts perform simple tasks such as concatenating files or generating inputs for other programs, so nothing is too big or small.

To submit or modify a script yourself:

  1. Create a Fork of the repository (A fork is a copy of a repository that you manage. Forks let you make changes to a project without affecting the CSD GitHub repo. You can fetch updates from or submit changes to the CSD GitHub repo with pull requests.
  2. Commit your changes to the forked repository.
  3. Create a Pull Request on the CSD GitHub repo.
  4. Once the code has been reviewed it will be merged into the CSD GitHub repo by our team.

 

More detailed instructions:

In order to add or modify existing scripts through GitHub, you will be required to have a GitHub Account (Free), and optionally you will want to have Git installed and setup on your computer.

  1. Create a Form of the CSD Python API Scripts Repo

    how to create a fork of a GitHub repo

    creating a fork of the github repo

  2. Clone the forked repository onto your PC 
    git clone <username/forked-repo>
  3. Make changes/add new script and don't forget the ReadMe file. Example script can be found in the repo.
  4. Create a new branch to add to your script 
    1 git branch <new_script_branch>
    2 git checkout <new_script_branch>
  5. Commit changes
    1 git add new_script.py
    2 git commit -m "Adding new_script"
    3 git push --set-upstream origin <new_script_branch>
  6. Switching to your new branch in GitHub, you can click on the "Contribute" button in your forked repo

    how to switch to a new branch in GitHub

    click the contribute button in your forked repo

  7. Click Pull Request

    click pull request on the GitHub repo

  8. Select the appropriate target and base

    select the target and base in GitHub

  9. Add information in the header and description

    Add information to the header and description in GitHub

  10. Click create Pull Request

  11. Now wait for our team to read your code and provide feedback.

 

How to get help on the CSD Python API or the CSD GitHub repo

If you have questions about using the CSD Python API, our technical support team are here to help. Contact us on support@ccdc.cam.ac.uk as normal.