nbgitpuller 1.2.2__tar.gz → 1.3.0b1__tar.gz

{nbgitpuller-1.2.2 → nbgitpuller-1.3.0b1}/CHANGELOG.md

@@ -1,3 +1,40 @@
+## 1.3
+
+### 1.3.0b1 (beta release) - 2026-02-04
+
+([full changelog](https://github.com/jupyterhub/nbgitpuller/compare/1.2.2...7af8b80))
+
+#### New features added
+
+- Add `copy error to clipboard` button [#382](https://github.com/jupyterhub/nbgitpuller/pull/382) ([@jnywong](https://github.com/jnywong), [@balajialg](https://github.com/balajialg), [@yuvipanda](https://github.com/yuvipanda))
+- Add link to go back to root when an error is thrown [#380](https://github.com/jupyterhub/nbgitpuller/pull/380) ([@cmarmo](https://github.com/cmarmo), [@jnywong](https://github.com/jnywong), [@nthiery](https://github.com/nthiery), [@yuvipanda](https://github.com/yuvipanda))
+
+#### Documentation improvements
+
+- Add targetPath to link generator. [#368](https://github.com/jupyterhub/nbgitpuller/pull/368) ([@ryanlovett](https://github.com/ryanlovett), [@consideRatio](https://github.com/consideRatio))
+- docs: Add warning about private tokens [#387](https://github.com/jupyterhub/nbgitpuller/pull/387) ([@jnywong](https://github.com/jnywong), [@ryanlovett](https://github.com/ryanlovett), [@yuvipanda](https://github.com/yuvipanda))
+- Update reference to link.rst [#363](https://github.com/jupyterhub/nbgitpuller/pull/363) ([@jnywong](https://github.com/jnywong), [@GeorgianaElena](https://github.com/GeorgianaElena))
+
+#### Continuous integration improvements
+
+- Bump actions/checkout from 5 to 6 [#381](https://github.com/jupyterhub/nbgitpuller/pull/381) ([@consideRatio](https://github.com/consideRatio))
+- Bump actions/setup-node from 5 to 6 [#377](https://github.com/jupyterhub/nbgitpuller/pull/377) ([@manics](https://github.com/manics))
+- Bump actions/setup-python from 5 to 6 [#376](https://github.com/jupyterhub/nbgitpuller/pull/376) ([@consideRatio](https://github.com/consideRatio))
+- Bump actions/checkout from 4 to 5 [#375](https://github.com/jupyterhub/nbgitpuller/pull/375) ([@consideRatio](https://github.com/consideRatio))
+- Bump actions/setup-node from 4 to 5 [#374](https://github.com/jupyterhub/nbgitpuller/pull/374) ([@consideRatio](https://github.com/consideRatio))
+- Support building on mybinder.org to ease testing [#258](https://github.com/jupyterhub/nbgitpuller/pull/258) ([@manics](https://github.com/manics), [@consideRatio](https://github.com/consideRatio), [@minrk](https://github.com/minrk))
+- [pre-commit.ci] pre-commit autoupdate [#371](https://github.com/jupyterhub/nbgitpuller/pull/371) ([@consideRatio](https://github.com/consideRatio))
+- [pre-commit.ci] pre-commit autoupdate [#366](https://github.com/jupyterhub/nbgitpuller/pull/366) ([@yuvipanda](https://github.com/yuvipanda))
+
+#### Contributors to this release
+
+The following people contributed discussions, new ideas, code and documentation contributions, and review.
+See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/use/#how-does-this-tool-define-contributions-in-the-reports).
+
+([GitHub contributors page for this release](https://github.com/jupyterhub/nbgitpuller/graphs/contributors?from=2025-01-27&to=2026-02-03&type=c))
+
+@balajialg ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Abalajialg+updated%3A2025-01-27..2026-02-03&type=Issues)) | @cmarmo ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Acmarmo+updated%3A2025-01-27..2026-02-03&type=Issues)) | @consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3AconsideRatio+updated%3A2025-01-27..2026-02-03&type=Issues)) | @GeorgianaElena ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3AGeorgianaElena+updated%3A2025-01-27..2026-02-03&type=Issues)) | @jacobtomlinson ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Ajacobtomlinson+updated%3A2025-01-27..2026-02-03&type=Issues)) | @jnywong ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Ajnywong+updated%3A2025-01-27..2026-02-03&type=Issues)) | @manics ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Amanics+updated%3A2025-01-27..2026-02-03&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Aminrk+updated%3A2025-01-27..2026-02-03&type=Issues)) | @nthiery ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Anthiery+updated%3A2025-01-27..2026-02-03&type=Issues)) | @ryanlovett ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Aryanlovett+updated%3A2025-01-27..2026-02-03&type=Issues)) | @yuvipanda ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Ayuvipanda+updated%3A2025-01-27..2026-02-03&type=Issues))
+
 ## 1.2
 
 ### 1.2.2 - 2025-01-27

{nbgitpuller-1.2.2/nbgitpuller.egg-info → nbgitpuller-1.3.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: nbgitpuller
-Version: 1.2.2
+Version: 1.3.0b1
 Summary: Jupyter Extension to do one-way synchronization of git repositories
 Home-page: https://github.com/jupyterhub/nbgitpuller
 Author: Peter Veerman, YuviPanda
@@ -25,6 +25,7 @@ Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: license
+Dynamic: license-file
 Dynamic: platform
 Dynamic: requires-dist
 Dynamic: summary

{nbgitpuller-1.2.2 → nbgitpuller-1.3.0b1}/nbgitpuller/__init__.py

@@ -1,5 +1,5 @@
-from .version import __version__ # noqa
-from .pull import GitPuller # noqa
+from nbgitpuller.version import __version__ # noqa
+from nbgitpuller.pull import GitPuller # noqa
 from jupyter_server.utils import url_path_join
 from tornado.web import StaticFileHandler
 import os

nbgitpuller-1.3.0b1/nbgitpuller/errors.py

@@ -0,0 +1,117 @@
+import subprocess
+import traceback
+
+
+class GitPullerError(Exception):
+    """
+    Structured error class used to branch frontend UI content based on its attributes.
+
+    Attributes:
+        code (str): Stable internal error code identifying the failure
+            type (e.g. ``"merge"``, ``"clone"``). This value is used by the
+            frontend to branch context specific UI behaviour.
+        message (str): External error message. This value is
+            safe to display in the frontend.
+        traceback (Optional[str]): Formatted traceback information captured from
+            the original exception for logging.    
+    """
+    def __init__(self, code: str = "unknown", message: str = "Unexpected error occurred", traceback_message=None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.traceback = traceback_message
+
+
+    def __str__(self):
+        return self.message
+
+
+    def to_dict(self):
+        return {
+            "code": self.code,
+            "message": self.message,
+            "traceback": self.traceback
+        }
+
+    @staticmethod
+    def format_traceback(exc):
+        tb = getattr(exc, "__traceback__", None)
+        traceback_message = ''.join(traceback.format_exception(type(exc), exc, tb)) if tb else None
+        return traceback_message
+
+
+    @classmethod
+    def from_exception(cls, exc: Exception) -> "GitPullerError":
+        """
+        Convert exceptions into a structured GitPullerError class.
+        """
+        if isinstance(exc, GitPullerError):
+            return exc
+        traceback_message = cls.format_traceback(exc)
+        if isinstance(exc, subprocess.CalledProcessError):
+            # Categorise errors based on specific git commands
+            if exc.cmd[1] == "clone":
+                return CloneError(traceback_message)
+            elif len(exc.cmd) >5 and exc.cmd[5] == "merge":
+                return MergeError(traceback_message)
+            elif exc.cmd[1] == "ls-remote":
+                return RemoteError(traceback_message)                
+        return cls(code="unknown", message=str(exc), traceback_message=traceback_message)
+
+
+
+class CloneError(GitPullerError):
+    code="clone"
+    message="Clone error detected"
+
+    def __init__(self, traceback_message=None):
+        super().__init__(
+            code = self.code,
+            message= self.message,
+            traceback_message=traceback_message
+        )
+
+
+class MergeError(GitPullerError):
+    code="merge"
+    message="Merge error detected"
+
+    def __init__(self, traceback_message=None):
+        super().__init__(
+            code = self.code,
+            message= self.message,
+            traceback_message=traceback_message
+        )
+
+class BranchExistError(GitPullerError):
+    code="branch_exist"
+    message="Branch does not exist"
+
+    def __init__(self, traceback_message=None):
+        super().__init__(
+            code = self.code,
+            message= self.message,
+            traceback_message=traceback_message
+        )
+
+class BranchResolveError(GitPullerError):
+    code="branch_resolve"
+    message="Branch name unresolved"
+
+    def __init__(self, traceback_message=None):
+        super().__init__(
+            code = self.code,
+            message= self.message,
+            traceback_message=traceback_message
+        )
+
+class RemoteError(GitPullerError):
+    code="ls_remote"
+    message="Remote content unavailable"
+
+    def __init__(self, traceback_message=None):
+        super().__init__(
+            code = self.code,
+            message= self.message,
+            traceback_message=traceback_message
+        )

{nbgitpuller-1.2.2 → nbgitpuller-1.3.0b1}/nbgitpuller/handlers.py

@@ -8,9 +8,10 @@ import os
 from queue import Queue, Empty
 import jinja2
 
-from .pull import GitPuller
-from .version import __version__
-from ._compat import get_base_handler
+from nbgitpuller.pull import GitPuller
+from nbgitpuller.errors import GitPullerError
+from nbgitpuller.version import __version__
+from nbgitpuller._compat import get_base_handler
 
 JupyterHandler = get_base_handler()
 
@@ -57,7 +58,7 @@ class SyncHandler(JupyterHandler):
         except gen.TimeoutError:
             await self.emit({
                 'phase': 'error',
-                'message': 'Another git operations is currently running, try again in a few minutes'
+                'message': 'Another git operation is currently running, try again in a few minutes'
             })
             return
 
@@ -65,6 +66,7 @@ class SyncHandler(JupyterHandler):
             repo = self.get_argument('repo')
             branch = self.get_argument('branch', None)
             depth = self.get_argument('depth', None)
+            backup = self.get_argument('backup', False)
             if depth:
                 depth = int(depth)
             # The default working directory is the directory from which Jupyter
@@ -84,7 +86,20 @@ class SyncHandler(JupyterHandler):
             self.set_header('content-type', 'text/event-stream')
             self.set_header('cache-control', 'no-cache')
 
-            gp = GitPuller(repo, repo_dir, branch=branch, depth=depth, parent=self.settings['nbapp'])
+            try:
+                gp = GitPuller(repo, repo_dir, branch=branch, depth=depth, backup=backup, parent=self.settings['nbapp'])
+            except Exception as e:
+                err = GitPullerError.from_exception(e)
+                err.traceback = GitPullerError.format_traceback(e)
+                err_out = err.to_dict()
+                await self.emit({
+                    'phase': 'error',
+                    'message': err_out["message"],
+                    'error': err_out,
+                    'output': err_out["traceback"],
+                })
+                raise err
+
 
             q = Queue()
 
@@ -110,17 +125,15 @@ class SyncHandler(JupyterHandler):
                 if progress is None:
                     break
                 if isinstance(progress, Exception):
+                    e = GitPullerError.from_exception(progress)
+                    err = e.to_dict()
                     await self.emit({
                         'phase': 'error',
                         'message': str(progress),
-                        'output': '\n'.join([
-                            line.strip()
-                            for line in traceback.format_exception(
-                                type(progress), progress, progress.__traceback__
-                            )
-                        ])
+                        'error': err,
+                        'output': err["traceback"]
                     })
-                    return
+                    raise e
 
                 await self.emit({'output': progress, 'phase': 'syncing'})
 
@@ -159,11 +172,12 @@ class UIHandler(JupyterHandler):
         # working directory) and we end up with weird failures
         targetpath = self.get_argument('targetpath', None) or \
                      self.get_argument('targetPath', repo.rstrip('/').split('/')[-1])
+        backup = self.get_argument('backup', False)
 
         if urlPath:
-            path = urlPath
+            path = urlPath if not backup else os.path.join(parent_reldir)
         else:
-            path = os.path.join(parent_reldir, targetpath, subPath)
+            path = os.path.join(parent_reldir, targetpath, subPath) if not backup else os.path.join(parent_reldir)
             if app.lower() == 'lab':
                 path = 'lab/tree/' + path
             elif path.lower().endswith('.ipynb'):
@@ -173,7 +187,7 @@ class UIHandler(JupyterHandler):
 
         self.write(
             jinja_env.get_template('status.html').render(
-                repo=repo, branch=branch, path=path, depth=depth, targetpath=targetpath, version=__version__,
+                repo=repo, branch=branch, path=path, depth=depth, targetpath=targetpath, backup=backup, version=__version__,
                 **self.template_namespace
             )
         )

{nbgitpuller-1.2.2 → nbgitpuller-1.3.0b1}/nbgitpuller/pull.py

@@ -4,9 +4,11 @@ import logging
 import time
 import argparse
 import datetime
+from itertools import count
 from traitlets import Integer, default
 from traitlets.config import Configurable
 from functools import partial
+from nbgitpuller.errors import BranchExistError, BranchResolveError
 
 
 def execute_cmd(cmd, **kwargs):
@@ -73,17 +75,22 @@ class GitPuller(Configurable):
         assert git_url
 
         self.git_url = git_url
-        self.branch_name = kwargs.pop("branch")
+        self.branch_name = kwargs.pop("branch", None)
+        self.repo_dir = repo_dir
+        backup = kwargs.pop("backup", False)
 
         if self.branch_name is None:
             self.branch_name = self.resolve_default_branch()
-        elif not self.branch_exists(self.branch_name):
-            raise ValueError(f"Branch: {self.branch_name} -- not found in repo: {self.git_url}")
+        else:
+            self.branch_exists(self.branch_name)
+
+        if backup and os.path.exists(self.repo_dir):
+            self.backup_repo_dir()
 
-        self.repo_dir = repo_dir
         newargs = {k: v for k, v in kwargs.items() if v is not None}
         super(GitPuller, self).__init__(**newargs)
 
+
     def branch_exists(self, branch):
         """
         This checks to make sure the branch we are told to access
@@ -107,7 +114,11 @@ class GitPuller(Configurable):
             _, ref = line.split()
             refs, heads, branch_name = ref.split("/", 2)
             branches.append(branch_name)
-        return branch in branches
+        if branch in branches:
+            return
+        else:
+            raise BranchExistError()
+
 
     def resolve_default_branch(self):
         """
@@ -127,11 +138,28 @@ class GitPuller(Configurable):
                     _, ref, head = line.split()
                     refs, heads, branch_name = ref.split("/", 2)
                     return branch_name
-            raise ValueError(f"default branch not found in {self.git_url}")
+            raise BranchResolveError()
         except subprocess.CalledProcessError:
-            m = f"Problem accessing HEAD branch: {self.git_url}"
-            logging.exception(m)
-            raise ValueError(m)
+            error = BranchResolveError()
+            logging.exception(error)
+            raise error
+
+    def backup_repo_dir(self):
+        """
+        Backup the existing repo_dir if URL parameter backup=true.
+        """
+        timestamp = datetime.datetime.now().strftime('%Y%m%d%H%M%S')
+        backup_dir = f"{self.repo_dir}_backup_{timestamp}"
+        if not os.path.exists(backup_dir):
+            os.rename(self.repo_dir, backup_dir)
+        else:
+            # Never clobber backup_dir if it somehow exists
+            base_dir = backup_dir
+            candidate = (f"{base_dir}.latest_{i}" for i in count())
+            while os.path.exists(backup_dir):
+                backup_dir = next(candidate)
+            os.rename(self.repo_dir, backup_dir)
+        logging.info('Backed up folder {}'.format(backup_dir))
 
     def pull(self):
         """
@@ -356,12 +384,14 @@ def main():
     parser.add_argument('git_url', help='Url of the repo to sync')
     parser.add_argument('branch_name', default=None, help='Branch of repo to sync', nargs='?')
     parser.add_argument('repo_dir', default='.', help='Path to clone repo under', nargs='?')
+    parser.add_argument('--backup', action='store_true', default=False, help='Whether to backup existing repo_dir if it exists')
     args = parser.parse_args()
 
     for line in GitPuller(
         args.git_url,
         args.repo_dir,
-        branch=args.branch_name if args.branch_name else None
+        branch=args.branch_name if args.branch_name else None,
+        backup=args.backup if args.backup else False,
     ).pull():
         print(line)