Drop python 2.7, add type hints (#271)

Author: tony

.github/workflows/tests.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["2.7", "3.x"]
+        python-version: [ '3.6', '3.7', '3.8' ]
     steps:
       - uses: actions/checkout@v1
       - name: Configure git

CHANGES

@@ -2,12 +2,22 @@
 
 Here are the changes for libvcs.
 
-## current
+## libvcs 0.9-current
 
 Generally speaking, refactor / magic is in the process of being stripped
 out in the next few releases. The API is subject to change significantly
 in pre-1.0 builds.
 
+[#271]:
+- Big version bump (0.5 -> 0.9)
+- Remove Python 2.7 support
+- Add annotations
+- Change `libvcs.git.GitRepo.status()` to return `GitStatus` named tuple
+- Breaking change: Repo objects now require `repo_dir` to be passed
+- Update black to 21.6b0
+
+[#271]: https://github.com/vcs-python/libvcs/pull/271
+
 ## libvcs 0.5 (2020-08-11)
 
 - [refactor] [#267] overhaul docs

docs/Makefile

@@ -159,7 +159,7 @@ checkbuild:
 	rm -rf $(BUILDDIR)
 	$(SPHINXBUILD) -n -q ./ $(BUILDDIR)
 
-WATCH_FILES= find .. -type f -not -path '*/\.*' | grep -i '.*[.]rst\$\|.*[.].md\|.*[.]py\$\|CHANGES\|TODO\|.*conf\.py' 2> /dev/null
+WATCH_FILES= find .. -type f -not -path '*/\.*' | grep -i '.*[.]rst\$\|.*[.]md\$\|.*[.]py\$\|CHANGES\|TODO\|.*conf\.py' 2> /dev/null
 
 watch:
 	if command -v entr > /dev/null; then ${WATCH_FILES} | entr -c $(MAKE) html; else $(MAKE) html; fi
@@ -170,13 +170,7 @@ serve:
 	@echo 'docs server running at http://localhost:${HTTP_PORT}/'
 	@echo
 	@echo '=============================================================='
-	@if test ${PYVERSION} -eq 2; then $(MAKE) serve_py2; else make serve_py3; fi
-
-serve_py2:
-	pushd _build/html; python2 -m SimpleHTTPServer ${HTTP_PORT}; popd
-
-serve_py3:
-	python -m http.server ${HTTP_PORT} --directory _build/html
+	poetry run python -m http.server ${HTTP_PORT} --directory _build/html
 
 dev:
 	$(MAKE) -j watch serve

docs/api.md

@@ -1,66 +1,58 @@
 # API Reference
 
-## Creating a repo object
+## Create from VCS url
 
 Helper methods are available in ``libvcs.shortcuts`` which
 can return a repo object from a single entry-point.
 
 ```eval_rst
-.. autofunction:: libvcs.shortcuts.create_repo
-
-.. autofunction:: libvcs.shortcuts.create_repo_from_pip_url
+.. automodule:: libvcs.shortcuts
+   :members:
 ```
 
-## Instantiating a repo by hand
-
-Tools like :func:`libvcs.shortcuts.create_repo` and
-:func:`libvcs.shortcuts.create_repo_from_pip_url` are just wrappers
-around instantiated these classes.
-
 See examples below of git, mercurial, and subversion.
 
+## Instantiating a repo by hand
+
 ### Git
 
 ```eval_rst
-.. autoclass:: libvcs.git.GitRepo
+.. automodule:: libvcs.git
    :members:
    :show-inheritance:
-
-.. autoclass:: libvcs.git.GitRemote
-   :members:
-   :show-inheritance:
-
-.. autofunction:: libvcs.git.extract_status
+   :inherited-members:
 ```
 
 ### Mercurial
 
 aka ``hg(1)``
 
 ```eval_rst
-.. autoclass:: libvcs.hg.MercurialRepo
+.. automodule:: libvcs.hg
    :members:
    :show-inheritance:
+   :inherited-members:
 ```
 
 ### Subversion
 
 aka ``svn(1)``
 
 ```eval_rst
-.. autoclass:: libvcs.svn.SubversionRepo
+.. automodule:: libvcs.svn
    :members:
    :show-inheritance:
+   :inherited-members:
 ```
 
-### Adding your own VCS
+### Under the hood
 
-Extending libvcs can be done through subclassing ``BaseRepo``.
+Adding your own VCS / Extending libvcs can be done through subclassing ``BaseRepo``.
 
 ```eval_rst
-.. autoclass:: libvcs.base.BaseRepo
-    :members:
-    :show-inheritance:
+.. automodule:: libvcs.base
+   :members:
+   :show-inheritance:
 ```
 
 ### Utility stuff

docs/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 import inspect
 import os
 import sys
@@ -20,6 +19,7 @@
 
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx_autodoc_typehints',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.napoleon',

docs/developing.md

@@ -51,7 +51,7 @@ Update `__version__` in `__about__.py` and `pyproject.toml`::
     git push
     git push --tags
     poetry build
-    poetry deploy
+    poetry publish
 
 [poetry]: https://python-poetry.org/
 [entr(1)]: http://eradman.com/entrproject/

libvcs/__about__.py

@@ -1,7 +1,7 @@
 __title__ = 'libvcs'
 __package_name__ = 'libvcs'
 __description__ = 'vcs abstraction layer'
-__version__ = '0.5.0'
+__version__ = '0.9.0a2'
 __author__ = 'Tony Narlock'
 __github__ = 'https://github.com/vcs-python/libvcs'
 __docs__ = 'https://libvcs.git-pull.com'

libvcs/__init__.py

@@ -1,7 +1,4 @@
-# -*- coding: utf-8 -*-
 """Repo package for libvcs."""
-from __future__ import absolute_import, print_function, unicode_literals
-
 import logging
 
 from .base import BaseRepo, RepoLoggingAdapter

libvcs/_compat.py

@@ -1,17 +1,36 @@
-# -*- coding: utf-8 -*-
 """Base class for Repository objects."""
-from __future__ import absolute_import, print_function, unicode_literals
-
 import logging
 import os
+from typing import NamedTuple
+from urllib import parse as urlparse
 
-from ._compat import implements_to_string, urlparse
 from .util import RepoLoggingAdapter, mkdir_p, run
 
 logger = logging.getLogger(__name__)
 
 
-@implements_to_string
+class VCSLocation(NamedTuple):
+    url: str
+    rev: str
+
+
+def convert_pip_url(pip_url: str) -> VCSLocation:
+    """Return repo URL and revision by parsing `libvcs.base.BaseRepo.url`."""
+    error_message = (
+        "Sorry, '%s' is a malformed VCS url. "
+        "The format is <vcs>+<protocol>://<url>, "
+        "e.g. svn+http://myrepo/svn/MyApp#egg=MyApp"
+    )
+    assert '+' in pip_url, error_message % pip_url
+    url = pip_url.split('+', 1)[1]
+    scheme, netloc, path, query, frag = urlparse.urlsplit(url)
+    rev = None
+    if '@' in path:
+        path, rev = path.rsplit('@', 1)
+    url = urlparse.urlunsplit((scheme, netloc, path, query, ''))
+    return VCSLocation(url=url, rev=rev)
+
+
 class BaseRepo(RepoLoggingAdapter, object):
 
     """Base class for repositories.
@@ -56,7 +75,7 @@ def __init__(self, url, repo_dir, progress_callback=None, *args, **kwargs):
 
     @classmethod
     def from_pip_url(cls, pip_url, *args, **kwargs):
-        url, rev = cls.get_url_and_revision_from_pip_url(pip_url)
+        url, rev = convert_pip_url(pip_url)
         self = cls(url=url, rev=rev, *args, **kwargs)
 
         return self
@@ -105,7 +124,7 @@ def run(
             cwd=cwd,
         )
 
-    def check_destination(self, *args, **kwargs):
+    def ensure_dir(self, *args, **kwargs):
         """Assure destination path exists. If not, create directories."""
         if os.path.exists(self.path):
             return True
@@ -122,22 +141,5 @@ def check_destination(self, *args, **kwargs):
 
         return True
 
-    @classmethod
-    def get_url_and_revision_from_pip_url(cls, pip_url):
-        """Return repo URL and revision by parsing `libvcs.base.BaseRepo.url`."""
-        error_message = (
-            "Sorry, '%s' is a malformed VCS url. "
-            "The format is <vcs>+<protocol>://<url>, "
-            "e.g. svn+http://myrepo/svn/MyApp#egg=MyApp"
-        )
-        assert '+' in pip_url, error_message % pip_url
-        url = pip_url.split('+', 1)[1]
-        scheme, netloc, path, query, frag = urlparse.urlsplit(url)
-        rev = None
-        if '@' in path:
-            path, rev = path.rsplit('@', 1)
-        url = urlparse.urlunsplit((scheme, netloc, path, query, ''))
-        return url, rev
-
     def __repr__(self):
         return "<{} {}>".format(self.__class__.__name__, self.repo_name)