Merge pull request #13 from Descent098/V0.3.0

V0.3.0

.deepsource.toml

@@ -0,0 +1,8 @@
+version = 1
+
+[[analyzers]]
+name = "python"
+enabled = true
+
+    [analyzers.meta]
+    runtime_version = "3.x.x"

CHANGELOG.md

@@ -1,19 +1,23 @@
 # Changelog
 
-## V 0.3.0 TBA
+## V 0.3.0 September 15th 2020
 
-Focus for this release was organization and finer details.
+Focus for this release is to make the whole API more user and dev friendly.
 
 Features:
-- .rpm support
 - Notification to let people know that they have to agree to the TOS of each piece of software
 - Ability to specify resources as dependencies
-- Generic command wrapper
-- Resource file format
+- Resource file format; use YAML files to specify a set of resources
+- Added download progress bars
+- Created function to add folders to path (will be implemented in next release)
 
 Development QOL:
 - Added user docs to the repo under /docs
-- ReadTheDocs Site
+- ReadTheDocs Site update
+- Added test suite
+- Added deepsource.io for quality validation
+- Added type hints to all functions/methods
+- Moved from universal planning board to version specific planning boards
 
 ## V 0.2.0 January 15th 2020
 

README.md

@@ -1,10 +1,31 @@
-![pystall logo](https://raw.githubusercontent.com/Descent098/pystall/master/pystall-logo.png)
+![pystall logo](https://raw.githubusercontent.com/Descent098/pystall/master/docs/img/pystall-logo.png)
 
 
 
 A system to automate installation and configuration of resources.
 
-
+## Table of Contents
+- [Features](#features)
+- [Quick-start](#quick-start)
+  - [Installation](#installation)
+    - [From PyPi](#from-pypi)
+    - [From Source](#from-source)
+  - [Basic Usage](#basic-usage)
+    - [Custom defined resources](#custom-defined-resources)
+    - [Built-in resource library](#built-in-resource-library)
+    - [Logging](#logging)
+    - [Additional Docs](#additional-docs)
+- [Roadmap](#roadmap)
+- [Assumptions](#assumptions)
+- [What is Pystall?](#what-is-pystall)
+
+## Features
+- Pull from a [built in resource library](https://pystall.readthedocs.io/en/latest/resource-library-list/) for quick installation
+- Define your own [custom local and remote resources](https://pystall.readthedocs.io/en/latest/quick-start/#custom-defined-resources)
+- Built in [logging](#logging)
+- The ability to build scrips into a [no dependency binary](https://pystall.readthedocs.io/en/latest/creating-binary-distributions/)
+- Specification of [resources in files](https://pystall.readthedocs.io/en/latest/file-resources/)
+- And more
 
 ## Quick-start
 

docs/custom-subclasses.md

@@ -38,14 +38,14 @@ class Resource(ABC):
     Examples
     --------
     Subclassing a static resource class to download static assets (images, videos etc.)
-    ```
+	\`\`\`
     class StaticResource(Resource):
         def __init__(self, label, extension, location, arguments = False, downloaded = False):
             super().__init__(label, extension, location, arguments, downloaded)
         def install(self):
             logging.info("No installation necessary for StaticResources")
             pass
-    ```
+    \`\`\`
     """
     def __init__(self, label, extension, location, arguments = False, downloaded = False):
 
@@ -54,7 +54,7 @@ class Resource(ABC):
         self.location = location
         self.arguments = arguments
         self.downloaded = downloaded
-
+    
     def download(self, file_path = False):
         """Downloads Resource from location specified in self.location of the instance.
         
@@ -67,28 +67,28 @@ class Resource(ABC):
         
         Examples
         --------
-        ```
+        \`\`\`
         python = EXEResource('python-installer', 'https://www.python.org/ftp/python/3.8.1/python-3.8.1.exe')
         python.download() # Downloads python installer exe to OS downloads folder
-        ```
+        \`\`\`
         """
         logging.info(f"Downloading {self.label}")
-
+    
         if not file_path:
             file_path = f"{DOWNLOAD_FOLDER}{os.sep}{self.label}{self.extension}"
-
+    
         if os.path.exists(file_path): # If file already exists
             self.downloaded = True
             self.location = file_path
             return
-
+    
         logging.info("Starting binary download")
         file_content = requests.get(self.location)
         open(file_path, 'wb').write(file_content.content) # Save file
         # TODO: Error catching
         self.downloaded = True
         self.location = file_path
-
+    
     @abstractmethod
     def install(self) -> None:
         """installation steps after all necessary downloads are completed"""
@@ -140,23 +140,23 @@ class ZIPResource(Resource):
         
     Examples
     --------
-    ```
+	\`\`\`
     from pystall.core import ZIPResource, build
     micro = ZIPResource("micro editor", "https://github.com/zyedidia/micro/releases/download/v1.4.1/micro-1.4.1-win64.zip")
     build(micro)
-    ```
+    \`\`\`
     """
     def __init__(self, label, location, arguments = False, downloaded = False, remove = True):
         super().__init__(label, ".zip", location, arguments, downloaded)
         self.remove = remove
-
+    
     def extract(self):
         """Extracts the .zip file."""
         extract_path = self.location[:-3:]
         logging.info(f"Extracting Zip archive {self.location} to {extract_path}")
         with ZipFile(self.location, "r") as archive:
                 archive.extractall(extract_path) # Strip extension and extract to folder
-
+    
     def install(self):
         """Extracts the .zip file and runs necessary installation steps. NOTE: Not yet implemented"""
         if self.downloaded:
@@ -165,7 +165,7 @@ class ZIPResource(Resource):
 
         else:
             logging.error(f"{self.name} failed to install due to not being downloaded")
-
+    
         if self.remove:
             logging.info(f"Removing installer {self.label}")
             os.remove(self.location)

docs/file-resources.md

@@ -0,0 +1,99 @@
+# Resource Library List
+
+As of version 0.3 you can now specify files for resources. This is done through a simple [YAML](https://docs.octoprint.org/en/master/configuration/yaml.html) file that allows you to specify multiple resources. The schema follows the exact same schema as the corresponding resource type. So for example with ```EXEResources``` it would follow the same schema as an ```EXEResource``` instance in python would.
+
+Below is an example of a "fully filled out" resource file with one ```exe``` resource:
+
+```yml
+Resources:
+  "python":
+    type: "exe"
+    location: "https://www.python.org/ftp/python/3.8.1/python-3.8.1.exe"
+    arguments: ["-a", "-b", "-c"]
+    downloaded: false
+    remove: true
+    overwrite_agreement: false
+    # Dependencies are not specified because you can just add them as a resource yourself
+```
+
+To then install from a resource file simply install ```pystall``` then run code such as this:
+
+```python
+from pystall.cli import build_from_file
+
+resource_file_path = "resource.yml" # Make this the path to your resource file
+
+build_from_file(resource_file_path) # Goes through and gets all the resources from the file and builds them
+```
+
+## Multiple resources in one file
+
+It's important to note you can add multiple resources to a single file. The important thing is you need the ```Resources``` top heading, and then each resource is defined with a string representing it's ```label``` (such as "python" above). 
+
+Here is an example of a resource file with multiple resources defined:
+
+```yml
+Resources:
+  "python":
+    type: "exe"
+    location: "https://www.python.org/ftp/python/3.8.1/python-3.8.1.exe"
+    downloaded: false
+    remove: true
+    overwrite_agreement: false
+  "Micro Zip":
+    type: "zip"
+    location: "https://github.com/zyedidia/micro/releases/download/v1.4.1/micro-1.4.1-win64.zip"
+    remove: true
+    overwrite_agreement: true
+```
+
+## Minimum setup
+
+The above example is a bit verbose, here is an example of the minimum necessary attributes specified for an ```EXEResource```:
+```yml
+Resources:
+  "python":
+    type: "exe"
+    location: "https://www.python.org/ftp/python/3.8.1/python-3.8.1.exe"
+```
+
+The only two attributes necessary for most resource types, are a **location**, and a **type**. **There are** however **exceptions** to this **with certain types**, so see the [Available Types](#available-types) section below for details about required fields.
+
+## Available Types
+
+Here is a table of the available types, the "YAML type" is the type you would use in the YAML file, and the "Python equivalent" is what it equates to in the python package. Additionally I have included all required fields for each type, be aware that **EVERYTHING is lowercase including the types and required fields**.
+
+| YAML Type | Python Equivalent | Required Fields           |
+| --------- | ----------------- | ------------------------- |
+| exe       | EXEResource       | type, location            |
+| msi       | MSIResource       | type, location            |
+| zip       | ZIPResource       | type, location            |
+| static    | StaticResource    | type, location, extension |
+| deb       | DEBResource       | type, location            |
+| ppa       | CUSTOMPPAResource | type, ppa, packages       |
+| tarball   | TARBALLResource   | type, location            |
+| apt       | CUSTOMPPAResource | type, packages            |
+
+Here is an example of a resource file with various types:
+
+```yml
+Resources:
+  "python":
+    type: "exe"
+    location: "https://www.python.org/ftp/python/3.8.1/python-3.8.1.exe"
+  "Micro Zip":
+    type: "zip"
+    location: "https://github.com/zyedidia/micro/releases/download/v1.4.1/micro-1.4.1-win64.zip"
+  "Wallpaper":
+    type: "static"
+    location: "https://images.unsplash.com/photo-1541599468348-e96984315921?ixlib=rb-1.2.1&auto=format&fit=crop&w=1600&h=500&q=60"
+    extension: '.png'
+  "Open Broadcast System":
+    type: "ppa"
+    ppa: "obsproject/obs-studio"
+    packages: ["obs-studio"]
+  "Steam":
+    type: "apt"
+    packages: ["steam"]
+```
+

docs/index.md

@@ -1,14 +1,21 @@
 # Welcome to the Pystall Docs
 
-<img src="https://raw.githubusercontent.com/Descent098/pystall/master/pystall-logo.png" alt="pystall logo" style="zoom:100%;  margin-left: auto; margin-right: auto; display: block;"/>
+<img src="https://raw.githubusercontent.com/Descent098/pystall/master/docs/img/pystall-logo.png" alt="pystall logo" style="zoom:100%;  margin-left: auto; margin-right: auto; display: block;"/>
 
 Pystall is a utility to help download & install resources on your system. Unlike regular configuration utilities pystall is designed to be run-and-done without leaving any daemons or obscure monitoring services running on your machine.
 
 
 
 If you just want to dive in check out the [quick-start](/quick-start) for the basic usage and installation details.
 
+## Features
 
+- Pull from a [built in resource library](https://pystall.readthedocs.io/en/latest/resource-library-list/) for quick installation
+- Define your own [custom local and remote resources](https://pystall.readthedocs.io/en/latest/quick-start/#custom-defined-resources)
+- Built in [logging](#logging)
+- The ability to build scrips into a [no dependency binary](https://pystall.readthedocs.io/en/latest/creating-binary-distributions/)
+- Specification of [resources in files](https://pystall.readthedocs.io/en/latest/file-resources/)
+- And more
 
 ## What is Pystall?
 

mkdocs.yml

@@ -6,6 +6,7 @@ nav:
     - Custom Subclasses: custom-subclasses.md
     - Resource Library List: resource-library-list.md
     - Creating Binary Distributions: creating-binary-distributions.md
+    - File Based Resources: file-resources.md
     - Contribution Guide: contribution-guide.md
 
 theme: readthedocs