Skip to content

Commit

Permalink
Remove undesired extra quote-space from Python API FOM
Browse files Browse the repository at this point in the history
Causes an extra 5mm indent in this long box.
  • Loading branch information
mih committed Oct 6, 2023
1 parent 51d4dc5 commit 8e66ea6
Showing 1 changed file with 65 additions and 65 deletions.
130 changes: 65 additions & 65 deletions docs/basics/101-130-yodaproject.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,95 +18,95 @@ a Python API for DataLad's functionality that you can read about in :ref:`a Find
:name: fom-pythonapi
:float:

.. _python:
.. _python:

Whatever you can do with DataLad from the command line, you can also do it with
DataLad's Python API.
Thus, DataLad's functionality can also be used within interactive Python sessions
or Python scripts.
All of DataLad's user-oriented commands are exposed via ``datalad.api``.
Thus, any command can be imported as a stand-alone command like this:
Whatever you can do with DataLad from the command line, you can also do it with
DataLad's Python API.
Thus, DataLad's functionality can also be used within interactive Python sessions
or Python scripts.
All of DataLad's user-oriented commands are exposed via ``datalad.api``.
Thus, any command can be imported as a stand-alone command like this:

.. code-block:: python
.. code-block:: python
>>> from datalad.api import <COMMAND>
>>> from datalad.api import <COMMAND>
Alternatively, to import all commands, one can use
Alternatively, to import all commands, one can use

.. code-block:: python
.. code-block:: python
>>> import datalad.api as dl
>>> import datalad.api as dl
and subsequently access commands as ``dl.get()``, ``dl.clone()``, and so forth.
and subsequently access commands as ``dl.get()``, ``dl.clone()``, and so forth.


The `developer documentation <https://docs.datalad.org/en/latest/modref.html>`_
of DataLad lists an overview of all commands, but naming is congruent to the
command line interface. The only functionality that is not available at the
command line is ``datalad.api.Dataset``, DataLad's core Python data type.
Just like any other command, it can be imported like this:
The `developer documentation <https://docs.datalad.org/en/latest/modref.html>`_
of DataLad lists an overview of all commands, but naming is congruent to the
command line interface. The only functionality that is not available at the
command line is ``datalad.api.Dataset``, DataLad's core Python data type.
Just like any other command, it can be imported like this:

.. code-block:: python
.. code-block:: python
>>> from datalad.api import Dataset
>>> from datalad.api import Dataset
or like this:
or like this:

.. code-block:: python
.. code-block:: python
>>> import datalad.api as dl
>>> dl.Dataset()
>>> import datalad.api as dl
>>> dl.Dataset()
A ``Dataset`` is a `class <https://docs.python.org/3/tutorial/classes.html>`_
that represents a DataLad dataset. In addition to the
stand-alone commands, all of DataLad's functionality is also available via
`methods <https://docs.python.org/3/tutorial/classes.html#method-objects>`_
of this class. Thus, these are two equally valid ways to create a new
dataset with DataLad in Python:
A ``Dataset`` is a `class <https://docs.python.org/3/tutorial/classes.html>`_
that represents a DataLad dataset. In addition to the
stand-alone commands, all of DataLad's functionality is also available via
`methods <https://docs.python.org/3/tutorial/classes.html#method-objects>`_
of this class. Thus, these are two equally valid ways to create a new
dataset with DataLad in Python:

.. code-block:: python
.. code-block:: python
>>> from datalad.api import create, Dataset
# create as a stand-alone command
>>> create(path='scratch/test')
[INFO ] Creating a new annex repo at /.../scratch/test
Out[3]: <Dataset path=/home/me/scratch/test>
# create as a dataset method
>>> ds = Dataset(path='scratch/test')
>>> ds.create()
[INFO ] Creating a new annex repo at /.../scratch/test
Out[3]: <Dataset path=/home/me/scratch/test>
>>> from datalad.api import create, Dataset
# create as a stand-alone command
>>> create(path='scratch/test')
[INFO ] Creating a new annex repo at /.../scratch/test
Out[3]: <Dataset path=/home/me/scratch/test>
# create as a dataset method
>>> ds = Dataset(path='scratch/test')
>>> ds.create()
[INFO ] Creating a new annex repo at /.../scratch/test
Out[3]: <Dataset path=/home/me/scratch/test>
As shown above, the only required parameter for a Dataset is the ``path`` to
its location, and this location may or may not exist yet.
As shown above, the only required parameter for a Dataset is the ``path`` to
its location, and this location may or may not exist yet.

Stand-alone functions have a ``dataset=`` argument, corresponding to the
``-d/--dataset`` option in their command-line equivalent. You can specify
the ``dataset=`` argument with a path (string) to your dataset (such as
``dataset='.'`` for the current directory, or ``dataset='path/to/ds'`` to
another location). Alternatively, you can pass a ``Dataset`` instance to it:
Stand-alone functions have a ``dataset=`` argument, corresponding to the
``-d/--dataset`` option in their command-line equivalent. You can specify
the ``dataset=`` argument with a path (string) to your dataset (such as
``dataset='.'`` for the current directory, or ``dataset='path/to/ds'`` to
another location). Alternatively, you can pass a ``Dataset`` instance to it:

.. code-block:: python
.. code-block:: python
>>> from datalad.api import save, Dataset
# use save with dataset specified as a path
>>> save(dataset='path/to/dataset/')
# use save with dataset specified as a dataset instance
>>> ds = Dataset('path/to/dataset')
>>> save(dataset=ds, message="saving all modifications")
# use save as a dataset method (no dataset argument)
>>> ds.save(message="saving all modifications")
>>> from datalad.api import save, Dataset
# use save with dataset specified as a path
>>> save(dataset='path/to/dataset/')
# use save with dataset specified as a dataset instance
>>> ds = Dataset('path/to/dataset')
>>> save(dataset=ds, message="saving all modifications")
# use save as a dataset method (no dataset argument)
>>> ds.save(message="saving all modifications")
**Use cases for DataLad's Python API**
**Use cases for DataLad's Python API**

Using the command line or the Python API of DataLad are both valid ways to accomplish the same results.
Depending on your workflows, using the Python API can help to automate dataset operations, provides an alternative
to the command line, or could be useful for scripting reproducible data analyses.
One unique advantage of the Python API is the ``Dataset``:
As the Python API does not suffer from the startup time cost of the command line,
there is the potential for substantial speed-up when doing many calls to the API,
and using a persistent Dataset object instance.
Using the command line or the Python API of DataLad are both valid ways to accomplish the same results.
Depending on your workflows, using the Python API can help to automate dataset operations, provides an alternative
to the command line, or could be useful for scripting reproducible data analyses.
One unique advantage of the Python API is the ``Dataset``:
As the Python API does not suffer from the startup time cost of the command line,
there is the potential for substantial speed-up when doing many calls to the API,
and using a persistent Dataset object instance.

.. importantnote:: Use DataLad in languages other than Python

Expand Down

0 comments on commit 8e66ea6

Please sign in to comment.