diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7a9b89ec..b639d760 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,13 +2,14 @@ ## Push Request Checklist -Before sending your pull requests, make sure you followed this list. +Before sending your pull requests, make sure you completed this checklist: -- Read [contributing guidelines](CONTRIBUTING.md). +- Read to the end [this document](CONTRIBUTING.md). - Read [Code of Conduct](CODE_OF_CONDUCT.md). -- Check if my changes are consistent with the [guidelines](CONTRIBUTING.md#user-content-general-guidelines-and-philosophy-for-contribution). -- Changes are consistent with the [Coding Style](CONTRIBUTING.md#user-content-coding-style). +- Check if your changes are consistent with the [Guidelines](CONTRIBUTING.md#user-content-general-guidelines-and-philosophy-for-contribution). +- Check if your changes are consistent with the [Coding Style](CONTRIBUTING.md#user-content-coding-style). - Manually test your code and add [Unit Tests](CONTRIBUTING.md#user-content-testing-best-practices). +- Be sure that you didn't brake anything by running all unit tests in folder unittests (right click on the folder and click on the green play). - [Document your work](CONTRIBUTING.md#user-content-documentation). ## How to become a contributor and submit your own code diff --git a/PYGUIDE.md b/PYGUIDE.md index eb0e7f8a..38b0686f 100644 --- a/PYGUIDE.md +++ b/PYGUIDE.md @@ -3,7 +3,7 @@ Coding style is just how the code looks, it's incredibly personal, and everyone has their style. -Your preferred architectures, variable and function naming style all of then impacts in your code style and how the others read and understand it, so it could become a significant burden if everyone is coding on his own. +Your preferred architectures, variable and function naming style all of then impacts in your code style and how the others read and understand it, so it could become a significant burden if everyone is coding on his or her own. At CERC, we are following the [PEP8](https://www.python.org/dev/peps/pep-0008/) with two spaces indentation instead of four. @@ -11,17 +11,17 @@ At CERC, we are following the [PEP8](https://www.python.org/dev/peps/pep-0008/) We use [PyCharm](https://www.jetbrains.com/pycharm/) as an integrated development environment and follow the tool's overall advice but the space indentation, which we set to two spaces instead of default four spaces. -For code analysis, we enforce the usage of [pylint](https://www.pylint.org/) with our own [custom style definition](pylintrc). +For code analysis, we enforce the usage of [pylint](https://www.pylint.org/) with our own [custom style definition](pylintrc). This file will be downloaded with the project the first time you clone it. ## Naming convention. -* Name your folders and files in lowercase. +* Name your folders and files in lowercase and use _ (underscore) to separate words. * Your class names must start in capital letters and follow the python CapWords pattern. -* Methods and properties that return lists must end in "s". +* Methods and properties that return lists must end in "s". Therefore, those that return single values, must be singular. * Methods and variables should be lowercase and use _ (underscore) as a word separator. * Constant names must be all capitals. -* Avoid the usage of "get_" and "set_" methods whenever possible, by using @property and @variable.setter decorators instead. -* "Private" methods, variables and properties start with _ (underscore) +* Avoid the usage of "get_" and "set_" methods whenever it is possible, use @property and @variable.setter decorators instead. +* "Private" methods, variables and properties start with _ (underscore). ## Imports. Place your imports at the top of the file, after the license and contact information @@ -43,7 +43,7 @@ Ensure that your imports are used and remove any unused. ## Object attributes and methods. -Use properties whenever possible and encapsulate the access to all the calculated object attributes into properties, as shown in the following example. +Use properties whenever it is possible. Encapsulate the access to all the calculated object attributes to avoid recalculating each time the property is called. ```python @@ -56,7 +56,7 @@ Use properties whenever possible and encapsulate the access to all the calculate ``` -And like in the following example for read and write properties. +And like in the following example for read and write properties: ```python @@ -70,7 +70,7 @@ And like in the following example for read and write properties. ``` -If your method or attribute returns a complex object use type hints as in this example. +If your method or attribute returns a complex object, use type hints as in this example: ```python @@ -79,7 +79,8 @@ If your method or attribute returns a complex object use type hints as in this e return self._object_changeable_attribute def new_complex_object(self, first_param, second_param) -> ComplexObject: - return ComplexObject(first_param, second_param, self.property) + other_needed_property = self.other_needed_property + return ComplexObject(first_param, second_param, other_needed_property) ``` @@ -96,11 +97,11 @@ Always access your variable through the method and avoid to access directly. ``` -### Coments. +### Comments. #### Code documentation. -All public classes, properties, and methods must have code comments. +All public classes, properties, and methods must have code comments. Code comments start with capital letters and end without period: ```python @@ -115,20 +116,42 @@ All public classes, properties, and methods must have code comments. @property def object_attribute(self): """ - My class object attributes + Get my class object attribute :return: int """ return self._object_attribute def operation(self, first_param, second_param): """ - multiplies object_attribute by two + Multiplies object_attribute by two :return: int """ return self.object_attribute * 2 ``` +Comments at getters and setters always start with Get and Set, and identity the type of variable at return (at getter) or the value (at setter): + +```python + + @property + def object_attribute(self): + """ + Get object attribute + :return: int + """ + return self._object_attribute + + @object_attribute.setter + def object_attribute(self, value): + """ + Set object attribute + :param value: int + """ + self._object_attribute = value + +``` + Attributes with known units should be explicit in method's comment. ```python diff --git a/WINDOWS_INSTALL.md b/WINDOWS_INSTALL.md index 4391a1da..8145cc46 100644 --- a/WINDOWS_INSTALL.md +++ b/WINDOWS_INSTALL.md @@ -7,58 +7,92 @@ Download the latest version of python and Microsoft c++ redistributable # Get the code. -1. First thing you will need is an editor for your source code, that's a personal choice, but we would like to recommend PyCharm community edition, an excellent open-source python editor. - -[PyCharm Community edition](https://www.jetbrains.com/pycharm/download/download-thanks.html?platform=windows&code=PCC) +1. First thing you will need is an editor for your source code, that's a personal choice, but we would like to recommend PyCharm community edition, an excellent open-source python editor. [PyCharm Community edition](https://www.jetbrains.com/pycharm/download/download-thanks.html?platform=windows&code=PCC) 2. Run the installer, and follow the installation instructions for PyCharm, you may change a few options, but the default ones should be fine. 3. Open PyCharm and click on **"Get from Version Control"**. -![pycharm wellcome screen](./docs/img/img_0.png) +![pycharm welcome screen](./docs/img/img_0.png) -4. Select Git as the version control and set the URL to [libs repository](https://binarycat.org/git/Guille/libs.git) as shown in the picture. +You can find it also at VCS -> Get from Version Control... +![pycharm get from version control](./docs/img/img_6.png) + + +4. Select Git as the version control, and set the URL to [libs repository](https://rs-loy-gitlab.concordia.ca/Guille/libs.git) as shown in the picture. +At the website, copy the URL from Clone -> Clone with HTTPS. ![pycharm get from version control screen](./docs/img/img_1.png) -You may need to install Git, by clicking at ***Download and install***. +You may need to install Git, by clicking at ***Download and install***. +If that message does not appear is because you have it already installed in your computer. -5. Click Clone to download CERC libs source code. +5. Click Clone to download CERC libs source code. You will end with a project like this: ![pycharm project screen](./docs/img/img_2.png) -you will end with a project like this. +6. Create your working branch by right clicking on the project folder (libs) -> Git -> Repository -> Branches: + +![create new branch 1](./docs/img/img_9.png) + +And then + New Branch: + +![create new branch 2](./docs/img/img_10.png) + +Give a name to your branch and open the tab Git at the down-left corner. Right click on your branch and push. + +![push new branch 1](./docs/img/img_11.png) + +![push new branch 2](./docs/img/img_12.png) + +Check that your branch appears in the Remote list: + +![check all set](./docs/img/img_13.png) + +If your branch is there, you are done with this part. # Configure PyCharm. We use two spaces as a tab instead of standard [pep8](https://www.python.org/dev/peps/pep-0008/) four spaces indentation. -This option could be configured in PyCharm at the settings screen, as shown in the picture. +This option can be configured in PyCharm at the settings screen, as shown in the picture. ![pycharm configuration screen](./docs/img/img_5.png) # Start your project. -1. Click on file new project like in the image. +1. At our Git (https://rs-loy-gitlab.concordia.ca/), click on New project: -![pycharm new project screen](./docs/img/img_3.png) +![git new project screen](./docs/img/img_14.png) -2. Go to project settings and add the libs project to your own, as shown in the picture. +The create a black project with the desired name (remember to follow our ![Coding Style](PYGUIDE.md)). + +![git give a name](./docs/img/img_15.png) + +And finally, clone it following the same steps as with ![libs](WINDOWS_INSTALL.md#get-the-code) (steps 3 to 5). + +2. Go to project settings and add the libs project to your own, by clicking on Add Content Root: ![pycharm new project screen](./docs/img/img_4.png) -3. Add your first file to your project and click in install requirements to automatically download all the dependencies. +![pycharm add libs](./docs/img/img_7.png) -4. When all the dependencies are satisfied, we are good to go to start importing our first model. +3. Add your first file to your project and click on install requirements to automatically download all the dependencies (in blue at top-right corner). -by adding the following code to our main.py +![pycharm add dependencies](./docs/img/img_8.png) -``` -from geometry.geometry_factory import GeometryFactory +4. When all the dependencies are satisfied, you are all set to start importing your first city model. + +Add the following code to your main.py + +```python + +from imports.geometry_factory import GeometryFactory city = GeometryFactory('citygml', 'myfile.gml').city +``` -``` \ No newline at end of file +5. Always remember to push your own project changes as the last thing you do before ending your working day! diff --git a/catalog_factories/catalog.py b/catalog_factories/catalog.py index b204558e..96b61726 100644 --- a/catalog_factories/catalog.py +++ b/catalog_factories/catalog.py @@ -5,6 +5,7 @@ Copyright © 2022 Concordia CERC group Project Coder Guille Gutierrez guillermo.gutierrezmorote@concordia.ca """ + class Catalog: """ Catalogs base class not implemented instance of the Catalog base class, catalog_factories will inherit from this class. diff --git a/docs/img/img_0.png b/docs/img/img_0.png new file mode 100644 index 00000000..5a3c6035 Binary files /dev/null and b/docs/img/img_0.png differ diff --git a/docs/img/img_1.png b/docs/img/img_1.png new file mode 100644 index 00000000..01770933 Binary files /dev/null and b/docs/img/img_1.png differ diff --git a/docs/img/img_10.png b/docs/img/img_10.png new file mode 100644 index 00000000..5e3528b4 Binary files /dev/null and b/docs/img/img_10.png differ diff --git a/docs/img/img_11.png b/docs/img/img_11.png new file mode 100644 index 00000000..cdf11b07 Binary files /dev/null and b/docs/img/img_11.png differ diff --git a/docs/img/img_12.png b/docs/img/img_12.png new file mode 100644 index 00000000..4a4ad8bd Binary files /dev/null and b/docs/img/img_12.png differ diff --git a/docs/img/img_13.png b/docs/img/img_13.png new file mode 100644 index 00000000..1542f551 Binary files /dev/null and b/docs/img/img_13.png differ diff --git a/docs/img/img_14.png b/docs/img/img_14.png new file mode 100644 index 00000000..822befbf Binary files /dev/null and b/docs/img/img_14.png differ diff --git a/docs/img/img_15.png b/docs/img/img_15.png new file mode 100644 index 00000000..820e0790 Binary files /dev/null and b/docs/img/img_15.png differ diff --git a/docs/img/img_16.png b/docs/img/img_16.png new file mode 100644 index 00000000..2b53174b Binary files /dev/null and b/docs/img/img_16.png differ diff --git a/docs/img/img_2.png b/docs/img/img_2.png new file mode 100644 index 00000000..dd262c9e Binary files /dev/null and b/docs/img/img_2.png differ diff --git a/docs/img/img_3.png b/docs/img/img_3.png new file mode 100644 index 00000000..34f7623b Binary files /dev/null and b/docs/img/img_3.png differ diff --git a/docs/img/img_4.png b/docs/img/img_4.png new file mode 100644 index 00000000..3818b949 Binary files /dev/null and b/docs/img/img_4.png differ diff --git a/docs/img/img_5.png b/docs/img/img_5.png new file mode 100644 index 00000000..7251bd7a Binary files /dev/null and b/docs/img/img_5.png differ diff --git a/docs/img/img_6.png b/docs/img/img_6.png new file mode 100644 index 00000000..470f0815 Binary files /dev/null and b/docs/img/img_6.png differ diff --git a/docs/img/img_7.png b/docs/img/img_7.png new file mode 100644 index 00000000..1c4a79ae Binary files /dev/null and b/docs/img/img_7.png differ diff --git a/docs/img/img_8.png b/docs/img/img_8.png new file mode 100644 index 00000000..37e12bba Binary files /dev/null and b/docs/img/img_8.png differ diff --git a/docs/img/img_9.png b/docs/img/img_9.png new file mode 100644 index 00000000..b3a1681a Binary files /dev/null and b/docs/img/img_9.png differ