Initial commit

Author: flyandlure

.gitignore

@@ -0,0 +1,3 @@
+venv
+.idea
+main.py

README.md

@@ -0,0 +1,70 @@
+# GitLab Issue Creator
+
+GitLab Issue Creator is a Python package that lets you create issues on a GitLab project. It is a simple wrapper around [Python GitLab](https://python-gitlab.readthedocs.io/en/stable/) with features limited only to the creation of issues. I built it to allow me to create GitLab issues for members of my teams based on the outputs of automated tasks.   
+
+## Installation
+To install GitLab Issue Creator enter the following command: 
+
+```python
+pip3 install git+https://github.com/practical-data-science/gitlab-issue-creator.git
+```
+
+### Authentication
+To authenticate with GitLab you need to create a personal access token. You can do this by going to your profile page and clicking on the [Personal Access Tokens](https://gitlab.com/-/profile/personal_access_tokens) tab.
+
+Import the `gitlab_issue_creator` module as `gic` and use the `authenticate()` function to authenticate with GitLab.
+
+```python
+import gitlab_issue_creator as gic
+
+gl = gic.authenticate('YOUR-PERSONAL-ACCESS-TOKEN')
+```
+
+### Usage
+To create an issue you need to call the `create_issue()` function. This takes the following parameters: gl (the GitLab object), project_id (the ID of the project you want to create the issue in), title (the title of the issue), description (the description of the issue), labels (a list of labels to apply to the issue), the milestone_id (the ID of the milestone), and assignee_id (the ID of the user to assign the issue to).
+
+```python
+issue = gic.create_issue(gl,
+                         project_id=987654321,
+                         title='Housekeeping / Fix URLs returning 404s',
+                         description='Please fix the below URLs returning 404s:', 
+                         assignee_id=54321,
+                         milestone_id=123456,
+                         labels=['Content'])
+```
+
+You can't attach a file to the main issue body in GitLab, so instead we'll create a note and attach the file of data to that. To do this we'll call the `upload_file_to_issue_note()` function. This takes the following parameters: gl (the GitLab object), project_id (the ID of the project you want to create the issue in), issue (the issue object you just created), filename (the name of the file), and filepath (the path and filename of the file).
+
+```python
+gic.upload_file_to_issue_note(gl,
+                              project_id=987654321,
+                              issue=issue,
+                              filepath='404s.csv',
+                              filename='/data/404s.csv')
+
+```
+
+### Helpers
+In order to create an issue you'll require various IDs that aren't exposed in the GitLab interface, such as the `project_id`, `assignee_id`, and `milestone_id`. 
+
+#### Get the project ID
+The `get_owned_projects()` function returns a list of projects that the user owns. You'll find the names and IDs of projects in here. 
+
+```python
+owned_projects = gic.get_owned_projects(gl)
+```
+
+#### Get the milestone ID
+The `get_project_milestones()` function returns a list of milestones for a project. You'll find the names and IDs of milestones in here.
+
+```python
+milestones = gic.get_project_milestones(gl, 123456789)
+```
+
+#### Get the user ID of a username
+The `get_user_by_username()` function returns the ID of a GitLab username. 
+
+```python
+user = gic.get_user_by_username(gl, 'your-username-here')
+```
+

gitlab_issue_creator/__init__.py

@@ -0,0 +1 @@
+from .issues import *

gitlab_issue_creator/issues.py

@@ -0,0 +1,127 @@
+"""
+GitLab Issue Creator
+"""
+
+import gitlab
+
+
+def authenticate(personal_access_token):
+    """Authenticates to GitLab.
+
+    Args:
+        personal_access_token (str): The PERSONAL_ACCESS_TOKEN URL.
+    """
+
+    gl = gitlab.Gitlab(private_token=personal_access_token)
+    gl.auth()
+
+    return gl
+
+
+def get_owned_projects(gl):
+    """Gets the owned projects.
+
+    Args:
+        gl (gitlab.Gitlab): The GitLab object.
+    """
+
+    owned_projects = gl.projects.list(owned=True, archived=0)
+    return owned_projects
+
+
+def get_project_by_id(gl, project_id):
+    """Gets the project by ID.
+
+    Args:
+        gl (gitlab.Gitlab): The GitLab object.
+        project_id (int): The project ID.
+    """
+
+    project = gl.projects.get(project_id)
+    return project
+
+
+def get_project_milestones(gl, project_id):
+    """Gets the project milestones.
+
+    Args:
+        gl (gitlab.Gitlab): The GitLab object.
+        project_id (int): The project ID.
+    """
+
+    project = gl.projects.get(project_id)
+    milestones = project.milestones.list(state='active')
+    return milestones
+
+
+def get_user_by_username(gl, username):
+    """Gets the user by username.
+
+    Args:
+        gl (gitlab.Gitlab): The GitLab object.
+        username (str): The username.
+    """
+
+    user = gl.users.list(search=username)
+    return user
+
+
+def create_issue(gl, project_id, title, description, assignee_id, milestone_id, labels: list):
+    """
+    Create an issue.
+
+    Args:
+        gl (gitlab.Gitlab): The GitLab object.
+        project_id (int): The project ID.
+        title (str): The issue title.
+        description (str): The issue description.
+        assignee_id (int): The assignee ID.
+        milestone_id (int): The milestone ID.
+        labels (list): The labels.
+    """
+
+    project = gl.projects.get(project_id)
+    issue = project.issues.create({'title': title,
+                                   'description': description,
+                                   'assignee_id': assignee_id,
+                                   'milestone_id': milestone_id,
+                                   'labels': labels})
+    return issue
+
+
+def add_note_to_issue(gl, project_id, issue, note):
+    """
+    Add a note to an issue.
+
+    Args:
+        gl (gitlab.Gitlab): The GitLab object.
+        project_id (int): The project ID.
+        issue (int): The issue object.
+        note (str): The note.
+    """
+
+    project = gl.projects.get(project_id)
+    issue.notes.create({'body': note})
+    return issue
+
+
+def upload_file_to_issue_note(gl, project_id, issue, filepath, filename):
+    """
+    Upload a file to an issue note.
+
+    Args:
+        gl (gitlab.Gitlab): The GitLab object.
+        project_id (int): The project ID.
+        issue (int): The issue object.
+        filepath (str): The file path.
+        filename (str): The file name.
+    """
+
+    project = gl.projects.get(project_id)
+    uploaded_file = project.upload(filename, filepath=filepath)
+    issue.notes.create({
+        "body": "See the [attached file]({})".format(uploaded_file["url"])
+    })
+
+    return issue
+

requirements.txt

@@ -0,0 +1 @@
+python-gitlab

setup.cfg

@@ -0,0 +1,2 @@
+[metadata]
+description-file = README.md

setup.py

@@ -0,0 +1,29 @@
+from setuptools import setup
+
+from os import path
+this_directory = path.abspath(path.dirname(__file__))
+with open(path.join(this_directory, 'README.md'), encoding='utf-8') as f:
+    long_description = f.read()
+
+setup(
+    name='GitLab Issue Creator',
+    packages=['gitlab_issue_creator'],
+    version='0.001',
+    license='MIT',
+    description='GitLab Issue Creator is a Python package for creating GitLab issues.',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
+    author='Matt Clarke',
+    author_email='[email protected]',
+    url='https://github.com/practicaldatascience/gitlab-issue-creator',
+    download_url='https://github.com/practicaldatascience/gitlab-issue-creator/archive/master.zip',
+    keywords=['python', 'gitlab'],
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'Intended Audience :: Developers',
+        'Topic :: Software Development :: Libraries :: Python Modules',
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 3.8',
+    ],
+    install_requires=['python-gitlab']
+)