collect-homework 0.1.0__tar.gz

collect_homework-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__
+test-folder
+

collect_homework-0.1.0/.gitignore~

@@ -0,0 +1 @@
+**/__pycache__

collect_homework-0.1.0/Makefile.pypi

@@ -0,0 +1,38 @@
+# derived from name in setup.py
+
+PYPI_NAME = $(shell python setup.py --name)
+VERSION = $(shell python setup.py --version)
+
+########## for uploading onto pypi
+# updated in May 2020 to use twine for uploads
+# run pip install twine if needed
+# to initialize twine credentials
+# keyring set upload.pypi.org parmentelat
+# keyring set test.pypi.org parmentelat
+
+VERSIONTAG = $(PYPI_NAME)-$(VERSION)
+GIT-TAG-ALREADY-SET = $(shell git tag | grep '^$(VERSIONTAG)$$')
+# to check for uncommitted changes
+GIT-CHANGES = $(shell echo $$(git diff HEAD | wc -l))
+
+# run this only once the sources are in on the right tag
+pypi: twine cleanpypi 
+	@if [ $(GIT-CHANGES) != 0 ]; then echo "You have uncommitted changes - cannot publish"; false; fi
+	@if [ -n "$(GIT-TAG-ALREADY-SET)" ] ; then echo "tag $(VERSIONTAG) already set"; false; fi
+	@if ! grep -q ' $(VERSION)' CHANGELOG.md ; then echo no mention of $(VERSION) in CHANGELOG.md; false; fi
+	@echo "You are about to release $(VERSION) - OK (Ctrl-c if not) ? " ; read _
+	git tag $(VERSIONTAG)
+	./setup.py sdist bdist_wheel
+	twine upload dist/*
+
+twine:
+	@type -p twine >& /dev/null || { echo ==== installing twine; pip install twine; }
+
+testpypi: cleanpypi
+	./setup.py sdist bdist_wheel
+	twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+
+cleanpypi:
+	rm -rf build dist
+
+.PHONY: pypi testpypi cleanpypi twine

collect_homework-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.3
+Name: collect-homework
+Version: 0.1.0
+Summary: Easily manage homework submissions
+Project-URL: Repository, https://github.com/flotpython/collect-homework
+Project-URL: Bug Tracker, https://github.com/flotpython/collect-homework/issues
+Author-email: Thierry Parmentelat <thierry.parmentelat@minesparis.psl.eu>
+License: MIT License
+Keywords: github,homework,submissions
+Requires-Python: >=3.8
+Requires-Dist: click
+Description-Content-Type: text/markdown
+
+# manage your student's homework
+
+## Description
+
+assuming you have asked your students to create a repo on github to submit their homework,
+this script will help you to clone all the repos in a folder, 
+and will help you fetch/pull/merge all the repos in the folder at once
+
+## Installation
+
+```bash
+pip install collect-homework
+```
+
+## Initial setup
+
+1. create a folder where you want to clone all the repos
+1. create a file named `00.ids` in the folder  
+   this file should contain the github ids of all the students, one id per line
+1. at that point  
+   ```bash
+   collect-homework clone
+   ```
+   will clone all the repos in the folder
+1. in order to pull all the repos in the folder  
+   ```bash
+   collect-homework pull
+   ```
+1. you get the gist of it; type
+   ```bash
+    collect-homework help
+    ```
+    to see all the available commands
+1. of particular interest is the `collect-homework summary` command, 
+   which will display the status of all the repos in the folder
+1. finally you can focus on one or several students by typing e.g. (this makes sense for most commands)
+   ```bash
+   collect-homework -s "JohnDoe JaneMartin" pull
+   ```
+   and then you can pull/merge/fetch only the repos of the students you have focused on
+
+## handling repo names
+
+assuming you run this command in a folder e.g. `/Users/johndoe/python-homework`:
+
+- then by default all the students are expected to have a repo named `python-homework`
+- if this does not match your setup, you can specify the repo name in the `00.reponame` file
+this one-line file should contain the name of all the repos, e.g. `python-homework-2021`
+- and if a student does not comply with that name, you can specify the repo name in the `00.repos` 
+  file by writing `student/repo` instead of just `student`  
+  (you can even put the complete github url instead if that's more convenient for you)

collect_homework-0.1.0/README.md

@@ -0,0 +1,51 @@
+# manage your student's homework
+
+## Description
+
+assuming you have asked your students to create a repo on github to submit their homework,
+this script will help you to clone all the repos in a folder, 
+and will help you fetch/pull/merge all the repos in the folder at once
+
+## Installation
+
+```bash
+pip install collect-homework
+```
+
+## Initial setup
+
+1. create a folder where you want to clone all the repos
+1. create a file named `00.ids` in the folder  
+   this file should contain the github ids of all the students, one id per line
+1. at that point  
+   ```bash
+   collect-homework clone
+   ```
+   will clone all the repos in the folder
+1. in order to pull all the repos in the folder  
+   ```bash
+   collect-homework pull
+   ```
+1. you get the gist of it; type
+   ```bash
+    collect-homework help
+    ```
+    to see all the available commands
+1. of particular interest is the `collect-homework summary` command, 
+   which will display the status of all the repos in the folder
+1. finally you can focus on one or several students by typing e.g. (this makes sense for most commands)
+   ```bash
+   collect-homework -s "JohnDoe JaneMartin" pull
+   ```
+   and then you can pull/merge/fetch only the repos of the students you have focused on
+
+## handling repo names
+
+assuming you run this command in a folder e.g. `/Users/johndoe/python-homework`:
+
+- then by default all the students are expected to have a repo named `python-homework`
+- if this does not match your setup, you can specify the repo name in the `00.reponame` file
+this one-line file should contain the name of all the repos, e.g. `python-homework-2021`
+- and if a student does not comply with that name, you can specify the repo name in the `00.repos` 
+  file by writing `student/repo` instead of just `student`  
+  (you can even put the complete github url instead if that's more convenient for you)

collect_homework-0.1.0/collect_homework/cli.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python
+
+"""
+Description: a script to manage a collection of git repositories,
+with one folder per student
+
+\b
+Config files:
+00.ids: where to store the students ids (and optionally reponames)
+00.reponame (optional): how the student repo is supposed to be named
+
+\b
+Workflow:
+0. you start with creating a file `00.ids` containing the github slugs (ids) of the students
+   all the ones that you are aware of at least
+1. ask each student to create a github repo named like e.g. numerique-homework
+   usually repo should be private (so students can't see each other's work),
+   in this case, they invite you, the teacher, as a collaborator
+2. beware to accept their invitation in a timely manner, as a github
+   invitation expires after typically 7 days
+3. create a fresh folder, named after the target reponame
+   so typically you could put all this in a folder
+   $HOME/git/ue12-p23-numerique/numerique-homework
+   alternately, if this convention does not suit you, you can instead
+   create a file named `00.reponame` containing the name of the repo
+   (e.g. numerique-homework)
+   this will be used to locate the student repos to be cloned
+4. as you receive new invitations, add them to a file named 00.ids if missing
+   see below for details on this file format
+5. run this script to clone all the repos with
+   collect-homework clone
+   this can be done several times, the existing folders will be skipped
+   so only the missing students are tried again
+6. if a student has misspelled their repo name
+   e.g. it is called homework-num instead of the expected numerique-homework
+   then tweak 00.ids (see the format below)
+7. iterate until you have all the slugs and all the repos cloned
+
+in the meanwhile, you can use all the functions below
+
+collect-homework --help
+
+\b
+collect-homework clone      will clone all repos
+collect-homework summary    will output a summary of all repos (nb of commits, last commit date, ...)
+collect-homework slugs      will output all slugs on stdout
+collect-homework repos      will output all ids on stdout
+collect-homework fetch      will fetch all repos
+collect-homework pull       will pull all repos
+collect-homework log1       will show the (full) last commit of each repo
+collect-homework l1         will show the last commit of each repo (one line per commit)
+collect-homework ln 4       same on the 4 last commits of each repo
+collect-homework missing    will output the folders missing
+                            i.e. students that have not yet created their repo
+
+you can use the -s option to restrict to one or several students, like so
+
+  collect-homework -s "bobarteam, john/ albert"
+
+the -s option expects exactly one argument, it will then use
+either space, comma or slash to cut the student names
+
+Format for 00.ids:
+
+\b
+00.ids is supposed to contain, one per line, the github ids of the students
+it can contain comments, starting with a #
+for each student you can use any of the following formats
+ - https://github.com/student/repo
+ - student/repo
+ - student
+
+when the repo is not provided, it is assumed to be
+  either the content of 00.reponame if that file exists
+  otherwise the name of the current folder
+"""
+
+import sys
+from pathlib import Path
+import re
+import subprocess
+
+import click
+
+from collect_homework.parallel_shells import ParallelShells
+
+
+CFG_REPONAME = "00.reponame"
+CFG_SLUGS = "00.ids"
+
+
+class Init:
+    """
+    reads current status
+    """
+
+    @staticmethod
+    def get_reponame():
+        cfg_reponame = Path(CFG_REPONAME)
+        if not cfg_reponame.exists():
+            return Path(".").absolute().parts[-1]
+        with cfg_reponame.open() as f:
+            return f.read().strip()
+
+    @staticmethod
+    def get_slugs(default_reponame):
+        cfg_slugs = Path(CFG_SLUGS)
+        result = {}
+        with cfg_slugs.open() as f:
+            for line in f:
+                if line.startswith('#'):
+                    continue
+                line = line.strip()
+                if "/" in line:
+                    slug, reponame = line.split("/")
+                    slug = slug.replace("https://github.com/", "")
+                else:
+                    slug = line
+                    reponame = default_reponame
+                result[slug] = reponame
+        return dict(sorted(result.items(), key=lambda x: x[0].lower()))
+
+    @staticmethod
+    def get_actual_repos():
+        for dir in Path(".").glob("*/.git"):
+            yield dir.parent.parts[-1]
+
+
+# globals
+
+REPONAME = Init.get_reponame()
+SLUGS = Init.get_slugs(REPONAME)
+DIRS = list(Init.get_actual_repos())
+
+
+
+def _git_proxy(message, *git_command):
+    """
+    Run a git command on all DIRS
+    """
+    for slug in Init.get_actual_repos():
+        if slug not in SLUGS:
+            continue
+        if message:
+            print(f"===== {message} in {slug}")
+        command = ["git", "-C", slug, *git_command]
+        # print(command)
+        subprocess.run(command)
+
+# message not used yet
+def _git_proxy_parallel(_message, *git_command):
+    """
+    Run a git command on all DIRS, but asynchronously
+    """
+    commands = []
+    for slug in Init.get_actual_repos():
+        if slug not in SLUGS:
+            continue
+        command = f"git -C {slug} {' '.join(git_command)}"
+        commands.append(command)
+    ParallelShells(commands).run()
+
+# the click CLI object
+@click.group(chain=True, help=sys.modules[__name__].__doc__)
+@click.option('-s', '--students', help="comma-separated")
+def cli(students):
+    if students is None:
+        return
+    global SLUGS
+    focus_slugs = {}
+    students = re.split(r'[/,\s]+', students)
+    for student in students:
+        if not student:
+            continue
+        if student not in SLUGS:
+            print(f"unknown student {student} in {CFG_SLUGS} - -s option ignored")
+            return
+        focus_slugs[student] = SLUGS[student]
+    SLUGS = focus_slugs
+
+
+# commands
+@cli.command('slugs')
+@click.option('-v', '--verbose', is_flag=True, default=False, help="show reponames", )
+def slugs(verbose):
+    for slug, reponame in SLUGS.items():
+        print(f"{slug}/{reponame}" if verbose else slug)
+
+@cli.command('dirs')
+def dirs():
+    for dir in sorted(DIRS, key=lambda x: x.lower()):
+        print(dir)
+
+@cli.command('missing')
+def missing():
+    for slug, reponame in SLUGS.items():
+        if slug not in DIRS:
+            print(slug)
+
+
+@cli.command('clone')
+def clone():
+    commands = []
+    for slug, reponame in SLUGS.items():
+        gitrepo = Path(slug) / "git"
+        if gitrepo.exists() and gitrepo.is_dir():
+            print(f"{slug} OK")
+            continue
+        commands.append(["git", "clone", "git@github.com:{slug}/{reponame}.git", slug])
+    ParallelShells(commands).run()
+
+
+@cli.command('urls')
+def urls(): _git_proxy("", "remote", "get-url", "origin")
+@cli.command('status')
+def status(): _git_proxy("STATUS", "status")
+@cli.command('s')
+def s(): _git_proxy("SHORT STATUS", "status", "--short", "--untracked-files=no")
+@cli.command('diff')
+def diff(): _git_proxy("DIFF", "diff")
+@cli.command('pull')
+def pull(): _git_proxy_parallel("PULL", "pull")
+@cli.command('fetch')
+def fetch(): _git_proxy_parallel("FETCH", "fetch")
+@cli.command('reset')
+def reset(): _git_proxy("RESET", "reset", "--hard")
+@cli.command('merge')
+def merge(): _git_proxy("MERGE", "merge", "origin/main")
+
+FORMAT = """--format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(dim bold red)%an%C(reset) - %s%C(red)%d%C(reset)'"""
+
+@cli.command('l1')
+def l1(): _git_proxy("", "log", "-1", FORMAT )
+@cli.command('log1')
+def log1(): _git_proxy("last commit", "log", "-1")
+@cli.command('l5')
+def l5(): _git_proxy( "LISTING 5 latest commits", "log", "--oneline", "--all", "--graph", "-5", FORMAT )
+
+@cli.command('ln')
+@click.argument('n', type=int)
+def ln(n): _git_proxy( f"LISTING {n} latest commits", "log", "--oneline", "--all", "--graph", f"-{n}", FORMAT )
+
+
+# pour a bit of shell in the mix
+summary_function = """
+function summary() {
+    local slug="$1"; shift
+    [[ -d $slug ]] || { printf '%27s ' $slug; echo MISSING; return; }
+    git -C $slug log >& /dev/null || { printf '%27s ' $slug; echo EMPTY; return; }
+    printf '%24s ' $slug
+    local nb_folders=$(find $slug -type d -depth +0 | grep -vE '/.git($|/)' | wc -l)
+    local nb_files=$(find $slug -type f | fgrep -v '/.git/' | wc -l)
+    local nb_git_files=$(git -C $slug ls-files | wc -l)
+    local nb_commits=$(git -C $slug log --oneline | wc -l)
+    local dateh=$(git -C $slug log -1 --format='%ah')
+    local date=$(git -C $slug log -1 --format='%ar')
+    printf "%2d folders - " $nb_folders
+    printf "%3d files - " $nb_files
+    printf "%3d git files - " $nb_git_files
+    printf "%3d commits - " $nb_commits
+    printf "last on %s (%s)" "$dateh" "$date"
+    echo
+}
+"""
+
+@cli.command('summary')
+def summary():
+    commands = []
+    for slug, _ in SLUGS.items():
+        commands.append(summary_function + f"summary {slug}")
+    ParallelShells(commands, echo=False).run()
+
+if __name__ == '__main__':
+    cli()

collect_homework-0.1.0/collect_homework/parallel_shells.py

@@ -0,0 +1,66 @@
+"""
+a utility to run several commands in parallel
+and show the results in order once they're all done
+"""
+
+from pathlib import Path
+import asyncio
+
+class ParallelShells:
+
+    def __init__(self, commands: list[str], echo=True):
+        self.commands = commands
+        self.echo = echo
+
+    def run(self):
+        """
+        a synchronous function that will run all
+        subcommands in parallel and show all the results
+        sequentially once they're all done
+        """
+        return asyncio.run(self._run())
+
+    async def _run(self):
+        """
+        an async function that will run all
+        subcommands in parallel and show all the results
+        sequentially once they're all done
+        """
+        tasks = []
+        for command in self.commands:
+            tasks.append(asyncio.create_task(self._run_command(command)))
+        for task in tasks:
+            await task
+
+    async def _run_command(self, command):
+        """
+        an async function that will run a single command
+        """
+        proc = await asyncio.create_subprocess_shell(
+            command,
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
+        stdout, stderr = await proc.communicate()
+        if self.echo:
+            print(f"===> {command}")
+        if stdout:
+            if stderr:                  # if no stderr, no need to separate
+                print("[stdout]:")
+            print(stdout.decode(), end="")
+        if stderr:
+            print("[stderr]:")
+            print(stderr.decode(), end="")
+
+if __name__ == "__main__":
+    commands = [
+        "ls -l",
+        "echo the sleeper; sleep 1",        # this one will be the last to finish
+        "echo hello",
+        "ls -l /tmp",
+        """function foo() {
+            echo "this is a function"
+            [ -f /etc/passwd ] && echo "passwd exists"
+        }
+        foo
+        """
+    ]
+    ParallelSh(commands).run()

collect_homework-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "collect-homework"
+version = "0.1.0"
+dependencies = [ "click", ]
+requires-python = ">=3.8"
+readme = "README.md"
+license = {text = "MIT License"}
+description = "Easily manage homework submissions"
+keywords = ["github", "homework", "submissions"]
+authors = [
+  {name = "Thierry Parmentelat", email = "thierry.parmentelat@minesparis.psl.eu"},
+]
+
+# [project.optional-dependencies]
+# gui = ["PyQt5"]
+# cli = [
+#   "click",
+# ]
+
+[tool.hatch.build.targets.wheel]
+packages = [ "collect_homework" ]
+
+
+[project.urls]
+Repository = "https://github.com/flotpython/collect-homework"
+"Bug Tracker" = "https://github.com/flotpython/collect-homework/issues"
+# Homepage = "https://example.com"
+# Documentation = "https://readthedocs.org"
+# Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
+
+
+[project.scripts]
+collect-homework = "collect_homework.cli:cli"