Credit parser and markdown language for scientific software.
Project description
CiteLang
Welcome to CiteLang! This is the first markdown syntax for citing software. Importantly, when you use CiteLang to reference software.
- Generate basic software credit trees
- Give credit accounting for dependencies!
No - we aren't using DOIs! A manually crafted identifier that a human has to remember to generate, in addition to a publication or release, is too much work for people to reasonably do. As research software engineers we also want to move away from the traditional "be valued like an academic" model. We are getting software metadata and a reference to an identifier via a package manager. This means that when you publish your software, you should publish it to an appropriate package manager.
Quick Start
CiteLang will require a libraries.io token, so you should login (it works with GitHub and other easy OAuth2 that don't require permissions beyond your email) and then go to the top right -> Settings -> API Key.
You'll want to export this in the environment:
export CITELANG_LIBRARIES_KEY=xxxxxxxxxxxxxxxxxxxxxxxxx
And of course you will need to install it, either from pip or the repository.
$ pip install citelang
or
$ git clone https://github.com/vsoch/citelang
$ cd citelang
$ pip install -e .
This will place an executable citelang
in your directory. For the commands below,
we will show interactions using the command line client and Python API.
Usage
For all cases from within Python, after exporing the token, we need to create a client.
from citelang.main import Client
client = Client()
Package Managers
Let's find package managers supported.
$ result = client.package_managers()
$ result.data
# This is how we print to the terminal
$ result.table()
Let's say you ran this, and you wanted to retrieve it again! Given that disable_cache
in your settings
is not set to True, you can call the function again and the data returned will be from the cache.
You can also ask for it verbatim:
$ cli.get_cache('package_managers')
...
{'name': 'Inqlude',
'project_count': 228,
'homepage': 'https://inqlude.org/',
'color': '#f34b7d',
'default_language': 'C++'}]
And from the command line:
$ citelang list
This gives us the listing of package managers that we can interact with. Since by default we create a cache of results (to not use our token ratelimit whenever possible) after calling this endpoint you'll find packages cached in your citelang home!
$ tree ~/.citelang/
/home/vanessa/.citelang/
├── cache
│ └── package_managers.json
└── settings.yml
This means if you make the call again, it will load data from here instead of making an API call. Note that there are actually two caches - the filesystem and memory cache. These are discussed in the config section.
Package
$ client.package(manager="pypi", name="requests")
And from the command line:
$ citelang package pypi requests
Or with a version:
$ citelang package pypi requests@2.27.1
Config
You don't technically need to do any custom configuration. However, if you want to make your own user-specific settings file:
$ citelang config inituser
You can also edit the default config in citelang/settings.yml if you control the install. We will be adding a table of settings when we add official documentation. For now, let's talk about specific variables.
disable_cache
This defaults to false, meaning we aren't disabling the cache. Not disabling the cache means we can cache different results in your citelang home. We do this to minimize API calls. The exception is for when you ask for a package without a version. Since we cannot be sure what the latest version is, we need to check again.
disable_memory_cache
Akin to the filesystem, given that you are using a client in a session (whether directly in Python or via a command provided by citelang) we will cache results in memory. E.g., if you are asking for multiple packages, we check first that you are asking for a valid manager. When we cache the list of managers available, this is possible without an extra API call.
TODO
- add citlang cache command group
- create documentation, settings table
- add support for version
Contributors
We use the all-contributors tool to generate a contributors graphic below.
Vanessasaurus 💻 |
License
This code is licensed under the MPL 2.0 LICENSE.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.