fastgit 0.1.3__tar.gz → 0.1.5__tar.gz

{fastgit-0.1.3/fastgit.egg-info → fastgit-0.1.5}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: fastgit
-Version: 0.1.3
+Version: 0.1.5
 Summary: Use git from python, fast
 Author-email: Jeremy Howard <github@jhoward.fastmail.fm>
-License: Apache-2.0
+License-Expression: Apache-2.0
 Project-URL: Repository, https://github.com/AnswerDotAI/fastgit
 Project-URL: Documentation, https://AnswerDotAI.github.io/fastgit
 Keywords: nbdev,jupyter,notebook,python
@@ -23,9 +23,9 @@ Dynamic: license-file
 
 <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
 
-`fastgit` is a thin Python wrapper for the `git` CLI: one [`Git`](https://AnswerDotAI.github.io/fastgit/core.html#git) object whose attribute calls run git commands, so if you know git, you already know fastgit. There is no reimplementation of git internals and no object model to learn – commands return git’s own output as (subclassed) `str`s.
+`fastgit` is a Python wrapper for the `git` command line, for use in scripts and interactive sessions. You call git subcommands as Python methods and pass options as keyword arguments.
 
-It is designed for interactive use and automation alike: errors print tersely by default (like git itself) or raise on request, exit codes that mean “no” rather than “failed” are returned normally, and passing `sync=False` gives an async client for servers and concurrent code.
+Commands run through the installed `git` executable and return its text output. There is no separate object model for repositories and commits. Both synchronous and asynchronous clients are available.
 
 ## Usage
 
@@ -39,7 +39,7 @@ $ pip install fastgit
 
 ### How to use
 
-Create a [`Git`](https://AnswerDotAI.github.io/fastgit/core.html#git) for any directory; every command runs with that directory as its working tree. Method names map to git subcommands, and results come back as stripped strings:
+Create a [`Git`](https://AnswerDotAI.github.io/fastgit/core.html#git) object for the directory you want to work in. Every command runs in that directory. The default local runner expands `~` and resolves relative paths. A custom `runner` receives the supplied directory unchanged. Results have leading and trailing whitespace stripped:
 
 ``` python
 import shutil, tempfile
@@ -61,7 +61,11 @@ g.commit(m='add .gitignore')
 
     '[main (root-commit) 5113ce1] add .gitignore\n 1 file changed, 1 insertion(+)\n create mode 100644 .gitignore'
 
-Keyword arguments become options: single-letter names are short options (`n=1` → `-n 1`), longer names long options with underscores turned into dashes, and `True` passes the bare flag:
+Keyword arguments become command-line options:
+
+- Single-letter names produce short options, such as `n=1` for `-n 1`.
+- Longer names produce long options, with underscores replaced by dashes.
+- A value of `True` passes the flag without a value.
 
 ``` python
 g.log(n=1, oneline=True)
@@ -85,7 +89,9 @@ g.current_branch, g.commits
 
     ('main', ['5113ce1 add .gitignore'])
 
-A failed command prints git’s message and returns `None`; pass `raise_exc=True` (per call or at init) to raise instead. Where git uses exit 1 to mean “no” rather than “error” – like `grep` finding nothing – the output is returned as usual, with the code on `.returncode`:
+Command output is returned in a `str` subclass with the exit code in `.returncode`. A failed command prints git’s message and returns `None`. Pass `raise_exc=True` to raise an exception instead. You can set this per call or when creating the client.
+
+Some git commands use exit code 1 for a negative result. For example, `grep` returns 1 when nothing matches. fastgit returns the output for these results without treating them as failures:
 
 ``` python
 res = g.grep('missing')
@@ -94,7 +100,7 @@ res.returncode
 
     1
 
-Pass `sync=False` for an async client: the same commands and properties, each returning an awaitable, so a server never blocks its event loop on git:
+Pass `sync=False` for an async client. Its commands and properties return awaitables. Waiting for git does not block the event loop:
 
 ``` python
 ag = Git(td, sync=False)

fastgit-0.1.5/README.md

@@ -0,0 +1,90 @@
+# fastgit
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+`fastgit` is a Python wrapper for the `git` command line, for use in scripts and interactive sessions. You call git subcommands as Python methods and pass options as keyword arguments.
+
+Commands run through the installed `git` executable and return its text output. There is no separate object model for repositories and commits. Both synchronous and asynchronous clients are available.
+
+## Usage
+
+### Installation
+
+Install latest from [pypi](https://pypi.org/project/fastgit/)
+
+``` sh
+$ pip install fastgit
+```
+
+### How to use
+
+Create a [`Git`](https://AnswerDotAI.github.io/fastgit/core.html#git) object for the directory you want to work in. Every command runs in that directory. The default local runner expands `~` and resolves relative paths. A custom `runner` receives the supplied directory unchanged. Results have leading and trailing whitespace stripped:
+
+``` python
+import shutil, tempfile
+```
+
+``` python
+td = tempfile.mkdtemp()
+g = Git(td)
+g.init(b='main')
+```
+
+    'Initialized empty Git repository in /private/var/folders/51/b2_szf2945n072c0vj2cyty40000gn/T/tmp8zyj76q7/.git/'
+
+``` python
+(g.d/'.gitignore').mk_write('*.bak')
+g.add('.gitignore')
+g.commit(m='add .gitignore')
+```
+
+    '[main (root-commit) 5113ce1] add .gitignore\n 1 file changed, 1 insertion(+)\n create mode 100644 .gitignore'
+
+Keyword arguments become command-line options:
+
+- Single-letter names produce short options, such as `n=1` for `-n 1`.
+- Longer names produce long options, with underscores replaced by dashes.
+- A value of `True` passes the flag without a value.
+
+``` python
+g.log(n=1, oneline=True)
+```
+
+    '5113ce1 add .gitignore'
+
+You can also pass path arguments after `--` using the `__` parameter:
+
+``` python
+g.log('--oneline', __=['.gitignore'])
+```
+
+    '5113ce1 add .gitignore'
+
+Frequent queries are properties:
+
+``` python
+g.current_branch, g.commits
+```
+
+    ('main', ['5113ce1 add .gitignore'])
+
+Command output is returned in a `str` subclass with the exit code in `.returncode`. A failed command prints git’s message and returns `None`. Pass `raise_exc=True` to raise an exception instead. You can set this per call or when creating the client.
+
+Some git commands use exit code 1 for a negative result. For example, `grep` returns 1 when nothing matches. fastgit returns the output for these results without treating them as failures:
+
+``` python
+res = g.grep('missing')
+res.returncode
+```
+
+    1
+
+Pass `sync=False` for an async client. Its commands and properties return awaitables. Waiting for git does not block the event loop:
+
+``` python
+ag = Git(td, sync=False)
+await ag.last_commit
+```
+
+    'add .gitignore'

fastgit-0.1.5/fastgit/__init__.py

@@ -0,0 +1,9 @@
+"""Use git from python, fast
+
+`fastgit` is a Python wrapper for the `git` command line, for use in scripts and interactive sessions. You call git subcommands as Python methods and pass options as keyword arguments.
+
+Commands run through the installed `git` executable and return its text output. There is no separate object model for repositories and commits. Both synchronous and asynchronous clients are available."""
+
+__version__ = "0.1.5"
+
+from .core import *

{fastgit-0.1.3 → fastgit-0.1.5}/fastgit/_modidx.py

@@ -20,6 +20,7 @@ d = { 'settings': { 'branch': 'main',
                               'fastgit.core.Git.top': ('core.html#git.top', 'fastgit/core.py'),
                               'fastgit.core.GitRes': ('core.html#gitres', 'fastgit/core.py'),
                               'fastgit.core.GitRes.__new__': ('core.html#gitres.__new__', 'fastgit/core.py'),
+                              'fastgit.core.GitRes.__repr__': ('core.html#gitres.__repr__', 'fastgit/core.py'),
                               'fastgit.core._arunlocal': ('core.html#_arunlocal', 'fastgit/core.py'),
                               'fastgit.core._depr_uname': ('core.html#_depr_uname', 'fastgit/core.py'),
                               'fastgit.core._gitcmd': ('core.html#_gitcmd', 'fastgit/core.py'),

{fastgit-0.1.3 → fastgit-0.1.5}/fastgit/core.py

@@ -18,12 +18,14 @@ from functools import cache
 _ok1 = {'merge-tree','merge-base','grep','check-ignore','diff','diff-index','diff-files','diff-tree','show-ref','config','rev-parse'}
 
 class GitRes(str):
-    "Git output `str`, carrying the command's `returncode`"
-    def __new__(cls, s, returncode=0):
-        self = super().__new__(cls, s)
-        self.returncode = returncode
+    "Git output text for display, with raw `stdout`, `stderr` and `returncode`"
+    def __new__(cls, stdout, stderr, returncode=0):
+        self = super().__new__(cls, (stdout + stderr).strip())
+        self.stdout,self.stderr,self.returncode = stdout,stderr,returncode
         return self
 
+    def __repr__(self): return str(self)
+
 # %% ../nbs/00_core.ipynb #e4c0a290
 def _gitcmd(path, *args, pre=None):
     cmd = ['git', '-C', str(Path(path).expanduser().resolve())] + list(args)
@@ -38,7 +40,7 @@ def _depr_uname(uname, pre):
 def _gitres(args, out, err, returncode, ok_exit):
     if ok_exit is None: ok_exit = 1 if args and args[0] in _ok1 else 0
     if returncode not in (0, *listify(ok_exit)): raise CalledProcessError(returncode, ['git', *args], out, err)
-    return GitRes((out + err).strip(), returncode)
+    return GitRes(out, err, returncode)
 
 def _runlocal(path, args, pre=None):
     "Default runner: compose the local argv and run it in a subprocess"
@@ -53,7 +55,7 @@ def callgit(
     ok_exit=None, # Extra accepted exit codes (default: 1 for `_ok1` commands)
     runner=None, # Replaces the local subprocess: `(path, args, pre) -> (stdout, stderr, returncode)`
 ):
-    "Run git in `path`, returning stripped stdout+stderr as a `GitRes`"
+    "Run git in `path`; its `GitRes` displays stripped output and retains raw stdout/stderr"
     out,err,rc = (runner or _runlocal)(path, list(args), pre=_depr_uname(uname, pre))
     return _gitres(args, out, err, rc, ok_exit)
 
@@ -73,9 +75,17 @@ def _longopts(cmd):
 # %% ../nbs/00_core.ipynb #97f78839
 class Git:
     "Run git commands in dir `d`; `sync=False` makes every command return an awaitable"
-    def __init__(self, d, pre=None, raise_exc=False, sync=True, runner=None): self.d,self.pre,self.raise_exc,self._sync,self.runner = Path(d).expanduser(),pre,raise_exc,sync,runner
-
-    def __call__(self, cmd, *args, mute_errors=False, raise_exc=None, ok_exit=None, **kwargs):
+    def __init__(self, d, pre=None, raise_exc=False, sync=True, runner=None): self.d,self.pre,self.raise_exc,self._sync,self.runner = Path(d),pre,raise_exc,sync,runner
+
+    def __call__(self,
+        cmd, # git subcommand to run
+        *args, # Positional arguments for the subcommand
+        mute_errors=False, # Suppress the printed ERROR line on failure?
+        raise_exc=None, # Raise `CalledProcessError` on failure? (default: `self.raise_exc`)
+        ok_exit=None, # Extra accepted exit codes (default: 1 for commands like `diff` where it isn't an error)
+        **kwargs # Become flags: short keys as `-k v`, long as `--key=v` (`_` to `-`; `True` bare, `False` dropped); `__` passes paths after `--`
+    ):
+        "Run `git cmd` in `self.d`, returning a `GitRes` (or an awaitable of one when `sync=False`)"
         paths = [str(p) for p in listify(kwargs.pop('__', None) or [])]
         args = listify(args)
         kwargs = {k:v for k,v in kwargs.items() if v is not False}

{fastgit-0.1.3 → fastgit-0.1.5/fastgit.egg-info}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: fastgit
-Version: 0.1.3
+Version: 0.1.5
 Summary: Use git from python, fast
 Author-email: Jeremy Howard <github@jhoward.fastmail.fm>
-License: Apache-2.0
+License-Expression: Apache-2.0
 Project-URL: Repository, https://github.com/AnswerDotAI/fastgit
 Project-URL: Documentation, https://AnswerDotAI.github.io/fastgit
 Keywords: nbdev,jupyter,notebook,python
@@ -23,9 +23,9 @@ Dynamic: license-file
 
 <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
 
-`fastgit` is a thin Python wrapper for the `git` CLI: one [`Git`](https://AnswerDotAI.github.io/fastgit/core.html#git) object whose attribute calls run git commands, so if you know git, you already know fastgit. There is no reimplementation of git internals and no object model to learn – commands return git’s own output as (subclassed) `str`s.
+`fastgit` is a Python wrapper for the `git` command line, for use in scripts and interactive sessions. You call git subcommands as Python methods and pass options as keyword arguments.
 
-It is designed for interactive use and automation alike: errors print tersely by default (like git itself) or raise on request, exit codes that mean “no” rather than “failed” are returned normally, and passing `sync=False` gives an async client for servers and concurrent code.
+Commands run through the installed `git` executable and return its text output. There is no separate object model for repositories and commits. Both synchronous and asynchronous clients are available.
 
 ## Usage
 
@@ -39,7 +39,7 @@ $ pip install fastgit
 
 ### How to use
 
-Create a [`Git`](https://AnswerDotAI.github.io/fastgit/core.html#git) for any directory; every command runs with that directory as its working tree. Method names map to git subcommands, and results come back as stripped strings:
+Create a [`Git`](https://AnswerDotAI.github.io/fastgit/core.html#git) object for the directory you want to work in. Every command runs in that directory. The default local runner expands `~` and resolves relative paths. A custom `runner` receives the supplied directory unchanged. Results have leading and trailing whitespace stripped:
 
 ``` python
 import shutil, tempfile
@@ -61,7 +61,11 @@ g.commit(m='add .gitignore')
 
     '[main (root-commit) 5113ce1] add .gitignore\n 1 file changed, 1 insertion(+)\n create mode 100644 .gitignore'
 
-Keyword arguments become options: single-letter names are short options (`n=1` → `-n 1`), longer names long options with underscores turned into dashes, and `True` passes the bare flag:
+Keyword arguments become command-line options:
+
+- Single-letter names produce short options, such as `n=1` for `-n 1`.
+- Longer names produce long options, with underscores replaced by dashes.
+- A value of `True` passes the flag without a value.
 
 ``` python
 g.log(n=1, oneline=True)
@@ -85,7 +89,9 @@ g.current_branch, g.commits
 
     ('main', ['5113ce1 add .gitignore'])
 
-A failed command prints git’s message and returns `None`; pass `raise_exc=True` (per call or at init) to raise instead. Where git uses exit 1 to mean “no” rather than “error” – like `grep` finding nothing – the output is returned as usual, with the code on `.returncode`:
+Command output is returned in a `str` subclass with the exit code in `.returncode`. A failed command prints git’s message and returns `None`. Pass `raise_exc=True` to raise an exception instead. You can set this per call or when creating the client.
+
+Some git commands use exit code 1 for a negative result. For example, `grep` returns 1 when nothing matches. fastgit returns the output for these results without treating them as failures:
 
 ``` python
 res = g.grep('missing')
@@ -94,7 +100,7 @@ res.returncode
 
     1
 
-Pass `sync=False` for an async client: the same commands and properties, each returning an awaitable, so a server never blocks its event loop on git:
+Pass `sync=False` for an async client. Its commands and properties return awaitables. Waiting for git does not block the event loop:
 
 ``` python
 ag = Git(td, sync=False)

{fastgit-0.1.3 → fastgit-0.1.5}/fastgit.egg-info/SOURCES.txt

@@ -1,5 +1,4 @@
 LICENSE
-MANIFEST.in
 README.md
 pyproject.toml
 fastgit/__init__.py

{fastgit-0.1.3 → fastgit-0.1.5}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=64"]
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "Use git from python, fast"
 readme = "README.md"
 requires-python = ">=3.9"
-license = {text = "Apache-2.0"}
+license = "Apache-2.0"
 authors = [{name = "Jeremy Howard", email = "github@jhoward.fastmail.fm"}]
 keywords = ['nbdev', 'jupyter', 'notebook', 'python']
 classifiers = ["Natural Language :: English", "Intended Audience :: Developers", "Development Status :: 3 - Alpha", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only"]

fastgit-0.1.3/MANIFEST.in

@@ -1,5 +0,0 @@
-include settings.ini
-include LICENSE
-include CONTRIBUTING.md
-include README.md
-recursive-exclude * __pycache__

fastgit-0.1.3/README.md

@@ -1,84 +0,0 @@
-# fastgit
-
-
-<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
-
-`fastgit` is a thin Python wrapper for the `git` CLI: one [`Git`](https://AnswerDotAI.github.io/fastgit/core.html#git) object whose attribute calls run git commands, so if you know git, you already know fastgit. There is no reimplementation of git internals and no object model to learn – commands return git’s own output as (subclassed) `str`s.
-
-It is designed for interactive use and automation alike: errors print tersely by default (like git itself) or raise on request, exit codes that mean “no” rather than “failed” are returned normally, and passing `sync=False` gives an async client for servers and concurrent code.
-
-## Usage
-
-### Installation
-
-Install latest from [pypi](https://pypi.org/project/fastgit/)
-
-``` sh
-$ pip install fastgit
-```
-
-### How to use
-
-Create a [`Git`](https://AnswerDotAI.github.io/fastgit/core.html#git) for any directory; every command runs with that directory as its working tree. Method names map to git subcommands, and results come back as stripped strings:
-
-``` python
-import shutil, tempfile
-```
-
-``` python
-td = tempfile.mkdtemp()
-g = Git(td)
-g.init(b='main')
-```
-
-    'Initialized empty Git repository in /private/var/folders/51/b2_szf2945n072c0vj2cyty40000gn/T/tmp8zyj76q7/.git/'
-
-``` python
-(g.d/'.gitignore').mk_write('*.bak')
-g.add('.gitignore')
-g.commit(m='add .gitignore')
-```
-
-    '[main (root-commit) 5113ce1] add .gitignore\n 1 file changed, 1 insertion(+)\n create mode 100644 .gitignore'
-
-Keyword arguments become options: single-letter names are short options (`n=1` → `-n 1`), longer names long options with underscores turned into dashes, and `True` passes the bare flag:
-
-``` python
-g.log(n=1, oneline=True)
-```
-
-    '5113ce1 add .gitignore'
-
-You can also pass path arguments after `--` using the `__` parameter:
-
-``` python
-g.log('--oneline', __=['.gitignore'])
-```
-
-    '5113ce1 add .gitignore'
-
-Frequent queries are properties:
-
-``` python
-g.current_branch, g.commits
-```
-
-    ('main', ['5113ce1 add .gitignore'])
-
-A failed command prints git’s message and returns `None`; pass `raise_exc=True` (per call or at init) to raise instead. Where git uses exit 1 to mean “no” rather than “error” – like `grep` finding nothing – the output is returned as usual, with the code on `.returncode`:
-
-``` python
-res = g.grep('missing')
-res.returncode
-```
-
-    1
-
-Pass `sync=False` for an async client: the same commands and properties, each returning an awaitable, so a server never blocks its event loop on git:
-
-``` python
-ag = Git(td, sync=False)
-await ag.last_commit
-```
-
-    'add .gitignore'

fastgit-0.1.3/fastgit/__init__.py

@@ -1,9 +0,0 @@
-"""Use git from python, fast
-
-`fastgit` is a thin Python wrapper for the `git` CLI: one `Git` object whose attribute calls run git commands, so if you know git, you already know fastgit. There is no reimplementation of git internals and no object model to learn -- commands return git's own output as (subclassed) `str`s.
-
-It is designed for interactive use and automation alike: errors print tersely by default (like git itself) or raise on request, exit codes that mean "no" rather than "failed" are returned normally, and passing `sync=False` gives an async client for servers and concurrent code."""
-
-__version__ = "0.1.3"
-
-from .core import *