Package: sidp-CanvasSync
# CanvasSync
Synchronise modules, assignments and files located on a Canvas by Instructure web server to your local computer.DescriptionCanvasSync helps students automatically synchronize modules, assignments & files located on their institutions Canvas web server
to a mirrored folder on their local computer. It traverses the folder hierarchy in Canvas from the top course level down to individual
files and creates a similar folder structure on the local computer:![](resources/overview.png)First, CanvasSync creates a folder hierarchy on the local computer reflecting the ‘Modules’ section on the Canvas server.
Files are stored in folders such as ../SyncFolder/Course/Module/SubFolder/file.txt. Both regular files, links to external
web pages as well as Canvas ‘Pages’ (HTML pages) representing assignments etc. may be downloaded. In addition, CanvasSync
may download Canvas assignments along with all linked files that can be found in the description of the assignment. Both
files stored on Canvas as well as external files will be detected.
Lastly, all files that do not fall into the above categories are downloaded and stored in the ‘Various Files’ folder.The user may specify various settings including:
- What type of items to be synchronized (files, HTML pages, external links)
- If assignments should be synchronized
- If CanvasSync should attempt to find external files described in the assignment descriptionInstallationThe easiest way to install and run CanvasSync is by using PIP. Download and install CanvasSync along with its
dependencies (see below) by running:` pip install CanvasSync `Alternatively, download the source distribution from thehttps://github.com/perslev/CanvasSync/tree/master/diston GitHub
(.tar.gz for UNIX and .zip for Windows) and run the following command on the distribution file:` pip installCanvasSync-<VERSION>.tar.gz`Lastly, you may use the supplied setup.py file to create your own source package or built package for your system.If you choose not to work with PIP, CanvasSync has the following dependencies that must be installed:DependenciesRequests  (http://docs.python-requests.org/en/master/)PyCrypto  (https://pypi.python.org/pypi/pycrypto)py-bcrypt (http://www.mindrot.org/projects/py-bcrypt/)six (https://pypi.python.org/pypi/six)Usage examplesAfter installation CanvasSync is launched by executing the following command in the console:` canvas `When launched without commandline arguments, CanvasSync will start synchronizing with previously specified settings or
prompt the user to enter new settings if no previous settings could be found.Command line arguments:
-i or –info will display the currently saved settings
-s or –setup will prompt the user to reinitialize settings
-h or –help will show the help screen
-S or –sync to synchronize
-p to specify settings password (potentially dangerous)SetupCanvasSync uses the Canvas LMS API (https://canvas.instructure.com/doc/api/) to pull resources on the Canvas server. In
order to authenticate with the server an authentication token must be generated on the Canvas web server. This is done by
going to the ‘Account’ section followed by ‘Settings’. Near the bottom under the ‘Approved integrations’ section, a new authentication
token may be generated. A token is a substitution to the familiar username-password based authentication and allows
3rd party applications such as CanvasSync to authenticate with the Canvas server API and pull resources. Please note that
by supplying an authentication token to the CanvasSync software, you allow CanvasSync to communicate with the Canvas server on
your behalf, see Disclaimer below.The process of generating a token is illustrated below:![](resources/auth_token.png)The authentication token is stored in an local file encrypted using a private password. Consequently, the user must
specify the password whenever CanvasSync is launched to synchronize at a later time. Passwords and/or auth tokens are
cannot and will not be shared with third parties.StatusbarFor MacOS CanvasSync has also a statusbar, for Windows a icon at the taskbar. From here you can initalise a Synchronisation manually or setup an automatic sync.<img src=”resources/macos_statusbar.png” width=”350”>   <img src=”resources/windows_systemtray.png” width=”350”>To run the Statusbar simply execute`/GUI/macos_statusbar.py`or`/GUI/windows_systemtray.py`. You can also add it to the system startup by executing`/GUI/startup_installer.py`. This script also contains a function to remove the statusbar from the system startup again.Still ToDo:
- quiting does not work
- preferences GUI still has to be added
(On MacOS the you have to grant CanvasSync access to access the KeyChain. CanvasSync saves the password here. ToDo: Make PopUp to give access if CanvasSync does not have access.)DisclaimerPlease note that by using CanvasSync the user allows the software to authenticate with the Canvas server on the users
behalf. CanvasSync stores the authentication key encrypted and locally and the key is never shared with 3rd parties.
The official version of CanvasSync will only pull resources from the server and never remove or modify resources on the
server. Modified/rogue versions of the software could however use the authentication token to remove or modify
resources that the user has access to on the server on the users behalf.CanvasSync is still in its early version and is not guaranteed to be stable.Use this software on your own risk :-)Additional resourceshttps://www.instructure.comhttps://canvas.instructure.com/doc/api/index.html0.1.0, 10-02-17 - Initial release.
0.1.1, 11-02-17 - Now supports Python 3.x
0.1.2, 11-02-17 - Now supports Python on Windows machines
0.1.3, 11-02-17 - Now supports Python on Windows machines, minor changes
0.1.4, 12-02-17 - Guided main menu implemented that presented when CanvasSync is invoked without parameters
0.1.5, 13-02-17 - Files locked for the user will no longer be downloaded, fixed some Python 3 related errors
0.1.6, 08-03-17 - Minor bug fixes, add package version .py file
0.1.7, 09-05-17 - If HTML Pages mentions files in the HTML body, they are downloaded and stored with HTML in subfolder
0.1.8, 16-05-17 - Fixed a bug that would make CanvasSync crash if HTML pages were linked from within an assignment
0.1.9, 30-08-17 - Added command line arguments to sync and specify password (https://github.com/JackKiefer)
0.2.0, 15-09-17 - Fixed bug that would cause the program to crash if password was not specified through command line argument
0.2.1, 25-09-17 - Allows users to rename courses. Fixed a bug running CanvasSync on Arch Linux.
0.2.2, 13-08-18 - Changed dependency from pycrypto to pycryptodome, added (debugging) option for running the canvas.py script targeting the local package version if PyPi version is not installed, added temporary fix to download up to 100 files under each entity
0.2.3, 31-08-19 - Rename courses feature was poorly supported and has been removed. When installing via PIP, the entry script is now invoked with ‘canvas’ instead of ‘canvas.py’. File- and folder names are now ‘cleaned’ for characters that are illegal in Windows and OneDrive sync processes on all operating systems (previously only on Windows). Fixed a various bugs. Minor refactoring performed.
0.2.4, 31-08-19 - Fixing minor error in packaging