From 968c448013d0d6f21ddc052f654f74d59c110f89 Mon Sep 17 00:00:00 2001 From: Dima Gerasimov Date: Sun, 12 Apr 2020 14:55:08 +0100 Subject: [PATCH] Update usage docs --- .gitignore | 1 - doc/SETUP.org | 90 +++++++++++++++++++++++++++++--------- my/books/kobo.py | 1 + setup.py | 26 +++++++++-- with_my.example => with_my | 10 +++-- 5 files changed, 99 insertions(+), 29 deletions(-) rename with_my.example => with_my (83%) diff --git a/.gitignore b/.gitignore index 3282944..7bd0d6e 100644 --- a/.gitignore +++ b/.gitignore @@ -207,6 +207,5 @@ pip-selfcheck.json # End of https://www.gitignore.io/api/python,emacs -with_my cov diff --git a/doc/SETUP.org b/doc/SETUP.org index 4a1958a..c2a0fab 100644 --- a/doc/SETUP.org +++ b/doc/SETUP.org @@ -2,9 +2,69 @@ Please don't be shy and raise issues if something in the instructions is unclear. You'd be really helping me, I want to make the setup as straightforward as possible! -* Setting up -** [optional] private configuration (=my.config=) -If you're not planning to use private configuration (some modules don't need it) you can skip straight to the next step. Still, I'd recommend you to read anyway. +* Few notes +I understand people may not super familiar with Python, PIP or generally unix, so here are some short notes: + +- only python3 is supported, and more specifically, ~python >= 3.5~. +- I'm using ~pip3~ command, but on your system you might only have ~pip~. + + If your ~pip --version~ says python 3, feel free to use ~pip~. + +- similarly, I'm using =python3= in the documentation, but if your =python --version= says python3, it's okay to use =python= + +- when you use ~pip install~, [[https://stackoverflow.com/a/42989020/706389][always pass =--user=]] +- I'm assuming the config directory is =~/.config=, but it's different on Mac/Windows. + + See [[https://github.com/ActiveState/appdirs/blob/3fe6a83776843a46f20c2e5587afcffe05e03b39/appdirs.py#L187-L190][this]] if you're not sure what's your user config dir. + +* Setting up the main package +This is a *required step* + +You can choose one of the following options: + +** local install +This is the most convenient option at the moment: + +1. Clone the repository: =git clone git@github.com:karlicoss/HPI.git /path/to/hpi= +2. Go into the project directory: =cd /path/to/hpi= +2. Run ~pip3 install --user -e .~ + + This will install the package in 'editable mode'. + It will basically be a link to =/path/to/hpi=, which means any changes in the cloned repo will be immediately reflected without need to reinstall anything. + + It's *extremely* convenient for developing and debugging. + +** use without installing +This is less convenient, but gives you more control. + +1. Clone the repository: =git clone git@github.com:karlicoss/HPI.git /path/to/hpi= +2. Go into the project directory: =cd /path/to/hpi= +3. Install the dependencies: ~python3 setup.py --dependencies-only~ +4. Use =with_my= script to get access to ~my.~ modules. + + For example: + + : /path/to/hpi/with_my python3 -c 'from my.pinboard import bookmarks; print(list(bookmarks()))' + + It's also convenient to put a symlink to =with_my= somewhere in your system path so you can run it from anywhere, or add an alias in your bashrc: + + : alias with_my='/path/to/hpi/with_my' + + After that, you can wrap your command in =with_my= to give it access to ~my.~ modules, e.g. see [[#usage-examples][examples]]. + +The benefit of this way is that you get a bit more control, explicitly allowing your scripts to use your data. + +** install from PIP + +This is still work in progress! + +* Setting up the modules +This is an *optional step* as some modules might work without extra setup. +But it depends on the specific module. + +** private configuration (=my.config=) +# TODO update this section.. +If you're not planning to use private configuration (some modules don't need it) you can skip straight to the next step. Still, I'd recommend you to read anyway. First you need to tell the package where to look for your data and external repositories, which is done though a separate (private) package named ~mycfg~. @@ -49,22 +109,10 @@ Some things (e.g. links to external packages like [[https://github.com/karlicoss That way you get easy imports (e.g. =import mycfg.repos.hypexport.model=) and proper IDE integration. # TODO link to post about exports? -** =with_my= helper script -# TODO FIXME dependencies? -# At the moment the package is not uploaded to PyPi yet, so can't -# TODO update this section -Next, point =with_my= script to your private configuration: - -#+begin_src bash -cp with_my.example with_my -vim with_my # specify path to your mycfg (if you want to use it) -#+end_src - -It's also convenient to put =with_my= somewhere in your system path so you can run it from anywhere. - -** Dependencies +** module dependencies Dependencies are different for specific modules you're planning to use, so it's hard to specify. -Generally you can just try using the module and then install missing packages via ~pip install --user~, should be fairly straightforward. + +Generally you can just try using the module and then install missing packages via ~pip3 install --user~, should be fairly straightforward. * Usage examples If you run your script with ~with_my~ wrapper, you'd have ~my~ in ~PYTHONPATH~ which gives you access to your data from within the script. @@ -94,10 +142,10 @@ You can use [[https://github.com/karlicoss/orger][orger]] to get Org-mode repres Some examples: *** [[https://github.com/burtonator/polar-bookshelf][Polar]] + This will convert Polar highlights into org-mode: -#+begin_src bash -with_my orger/modules/polar.py --to polar.org -#+end_src + +: with_my orger/modules/polar.py --to polar.org ** =demo.py= read/run [[../demo.py][demo.py]] for a full demonstration of setting up Hypothesis (it uses public annotations data from Github) diff --git a/my/books/kobo.py b/my/books/kobo.py index 6235556..48b4606 100644 --- a/my/books/kobo.py +++ b/my/books/kobo.py @@ -1,6 +1,7 @@ """ Kobo e-ink reader: annotations and reading stats """ +from .. import init from typing import Callable, Union, List diff --git a/setup.py b/setup.py index 18a2dd8..326f84a 100644 --- a/setup.py +++ b/setup.py @@ -1,10 +1,14 @@ #!/usr/bin/env python3 -from setuptools import setup, find_packages +from setuptools import setup, find_packages # type: ignore + +INSTALL_REQUIRES = [ + 'appdirs' +] def main(): setup( name='my', - version='0.5', + version='0.0.20200412', description='A Python interface to my life', url='https://github.com/karlicoss/HPI', author='Dmitrii Gerasimov', @@ -40,8 +44,24 @@ def main(): 'pylint', ], }, + install_requires=INSTALL_REQUIRES, ) if __name__ == '__main__': - main() + import argparse + p = argparse.ArgumentParser() + p.add_argument('--dependencies-only', action='store_true') + args, _ = p.parse_known_args() + if args.dependencies_only: + cmd = ['pip3', 'install', '--user', *INSTALL_REQUIRES] + scmd = ' '.join(cmd) + import os + xx = input(f'Run {scmd} [y/n] ') + if xx.strip() == 'y': + os.execvp( + 'pip3', + cmd + ) + else: + main() diff --git a/with_my.example b/with_my similarity index 83% rename from with_my.example rename to with_my index 9a0824e..995160d 100755 --- a/with_my.example +++ b/with_my @@ -13,7 +13,8 @@ Feel free to use your preferred way of managing these packages otherwise. # can be empty if you're not planning to use modules that use private configuration # otherwise see readme to learn how to set it -MYCFG_DIR = '' +from pathlib import Path +MY_CONFIG = str(Path('~/.config/my').expanduser()) ###### @@ -22,13 +23,12 @@ MYCFG_DIR = '' from pathlib import Path # directory where 'my' package is present -MY_DIR = str(Path(__file__).absolute().parent) +MY_DIR = str(Path(__file__).resolve().absolute().parent) if __name__ == '__main__': import os import sys - def upd(envvar, path): if len(path) == 0: return @@ -42,7 +42,9 @@ if __name__ == '__main__': # TODO wonder why py.typed file in mycfg didn't help? for v in ['MYPYPATH', 'PYTHONPATH']: upd(v, MY_DIR) # TODO not sure if it should do it if you use install -e? - upd(v, MYCFG_DIR) + + # TODO not sure if it should update PYTHONPATH for my_config here?? + upd(v, MY_CONFIG) rest = sys.argv[1:] os.execvp(rest[0], rest)