| Name | palje JSON |
| Version |
2.3.1
JSON |
| download |
| home_page | None |
| Summary | A tool for creating hierarchical documentation of SQL Server databases to Confluence wiki. |
| upload_time | 2024-09-27 06:08:11 |
| maintainer | ALM Partners Oy |
| docs_url | None |
| author | ALM Partners Oy |
| requires_python | >=3.11 |
| license | Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. |
| keywords |
palje
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Palje
====================
# Description
Palje is a tool for creating hierarchical documentation of SQL Server databases to Confluence wiki.
# Dependencies
* [pyodbc](https://pypi.org/project/pyodbc/)
* [requests](https://pypi.org/project/requests/)
# Install Guide
## PyPI
Install from [Python Package Index](https://pypi.org/) with the following command:
```
pip install palje
```
## Clone and install
1. Clone this repository
2. Install with pip
```
cd .\palje
pip install [-e] .
```
## Development environment
Install and set up dev and test tooling with commands:
```
pip install -e .[dev, test]
pre-commit install
```
This takes `black` code formatting in use via `pre-commit`.
# Usage
Palje can be used either from the command line (CLI) or from the graphical user interface (GUI).
Notice that there are two versions of the command-line tool: legacy `palje` and newer `palje2`. See below for details.
## Prerequisites
- Read access to the MSSQL database you wish to document
- Data is read from documented database, information schema and system views
- You can use either SQL authentication or Windows authentication (if available)
- Write access to Confluence space on which you wish to create the documentation pages
- Atlassian API Token for your account
- Palje uses your registered account email and API token to authenticate to Confluence Cloud
- Go to https://id.atlassian.com/manage/api-tokens
- Choose "Create API token"
- Give it a name
- Token password will be created automatically, save this password
## Remarks on compatibility
- Palje has been tested on multiple SQL Server versions, including [SQL Server images](https://hub.docker.com/_/microsoft-mssql-server)
- Palje has been tested on cloud instances, such as Azure SQL Database
- Palje supports Azure Active Directory authentication with argument --authentication "AAD"
- Palje has been tested to work with Confluence Cloud
- There is a possibility that Palje works with Confluence Server since the Server REST API is similar to Cloud REST API
- Notice that the authentication works differently in Confluence Server
## Graphical user-interface
Notice that GUI may be lacking some of the more advanced features that are available via CLI.
Launch Palje GUI from a shell with command:
```
palje-gui
```
See the CLI documentation below for information on various parameters - it all applies to GUI, too.
## CLI and arguments (current palje2 version)
In comparison to `palje`, the new `palje2` CLI is more flexible and adds more features for managing Confluence documentation e.g. deletion of Confluence page hierarchies.
See online help for up-to-date documentation for available options and sub-commands.
```
palje2 --help
```
To see specific documentation for a sub-command, use the -h/--help switch after the sub-command e.g.
```
palje2 document --help
palje2 delete --help
```
### Parameters from ENV vars
With `palje2` many parameters (e.g. Confluence authentication params) can be set into ENV variables from where they are automatically read at runtime. This makes continous use more user-friendly: less repetative typing, shorter and clearer commands, sensitive data stays out of sight, ...
Notice that using ENV vars is optional: alternatively you can type parameters on the command line and/or leave them off and let `palje2` interactively prompt for any required parameter values.
See the online-documentation for supported ENV vars and their exact names.
Example of setting ENV vars in PowerShell:
```
$env:PALJE_ATLASSIAN_USER_ID = "firstname.lastname@organization.org"
$env:PALJE_ATLASSIAN_API_TOKEN = "S3CR3T"
$env:PALJE_DB_SERVER = "localhost,14330"
...
```
If you want to unset an ENV var, you can do it like:
```
$env:PALJE_DB_PASSWORD = $null
```
## CLI and arguments (legacy version)
See online help for up-to-date documentation for available options.
```
palje -h
```
### Basic syntax
```
palje confluence-url space server database
--parent-page PARENT_PAGE
--schemas SCHEMAS [SCHEMAS ...]
--dependent DEPENDENT [DEPENDENT ...]
--db-driver DB_DRIVER
--authentication AUTHENTICATION
```
| Argument | Required | Description | Type | Default Value |
| --- | --- | --- | --- | --- |
| confluence-url | Yes | The organisation's atlassian root page, https://<your-org>.atlassian.net/ | str | |
| space | Yes | Space key of the Confluence space, in which the documentation is created | str | |
| server | Yes | Host name of the SQL Server. Include port with comma | str | |
| database | Yes | Name of the database that is documented | str | |
| parent-page | No | Name or title of the Confluence page, under which the documentation is created | str | If page is not given, the documentation will be created to top level (under pages) |
| schemas | No | Names of the schemas that are documented | list of str | If schemas not given, all schemas will be documented |
| dependent | No | Names of the databases, where object dependencies are sought | list of str | If databases not given, dependencies are sought only in documented database |
| db-driver | No | Name of the database driver | str | "ODBC Driver 17 for SQL Server" |
| authentication | No | Authentication method to use. Options are "SQL", "Windows", "AAD" and "AzureIdentity". | str | "SQL"
## Usage example
### Command-line interface
```
# Run via a configured script endpoint ("palje.exe")
palje "https://<your-org>.atlassian.net/" TEST "localhost,1433" MY_DB --schemas dbo store --dependent MY_OTHER_DB --authentication "SQL"
# Optionally you also run palje as a Python library module
python -m palje "https://<your-org>.atlassian.net/" TEST "localhost,1433" MY_DB --schemas dbo store --dependent MY_OTHER_DB --authentication "SQL"
```
### Output
```
User for localhost,1433.MY_DB. If you wish to use Windows Authentication, hit enter: sa
Password for user sa:
Confluence user for https://<your-org>.atlassian.net/: example.user@youremail.com
Atlassian API token for user example.user@youremail.com:
--------------------------
Object dependencies are queried from the following databases: MY_DB, MY_OTHER_DB
--------------------------
Page DATABASE: MY_DB created.
Page MY_DB.dbo created.
Page Tables MY_DB.dbo created.
Page MY_DB.dbo.schema_version created.
Page MY_DB.store created.
Page Tables MY_DB.store created.
Page MY_DB.store.Clients created.
Page MY_DB.store.Products created.
Page Procedures MY_DB.store created.
Page MY_DB.store.spSELECT created.
```
### Result
#### Page hierarchy in Confluence
#### Page showing the database objects
#### Page showing the table information
### Re-run
Re-running the command will result updating the existing pages
```
Page DATABASE: MY_DB updated.
Page MY_DB.dbo updated.
Page Tables MY_DB.dbo updated.
Page MY_DB.dbo.schema_version updated.
Page MY_DB.store updated.
Page Tables MY_DB.store updated.
Page MY_DB.store.Clients updated.
Page MY_DB.store.Products updated.
Page Procedures MY_DB.store updated.
Page MY_DB.store.spSELECT updated.
```
If new objects have been created to database before re-run, new pages will be created for these objects. For example, if new procedure `store.spNEW_SELECT` is created to database, a new page `MY_DB.store.spNEW_SELECT` is created under page `Procedures MY_DB.store`.
Notice that if you delete objects from database, Palje won't delete the corresponding pages from Confluence. You must manually delete the pages from wiki.
## Tests
Run tests with [tox](https://pypi.org/project/tox/)
```
pip install tox # OR install as an optional depencency with palje itself: pip install .[test]
tox -- --mssql_host MSSQL_HOST --mssql_port MSSQL_PORT --mssql_username MSSQL_USER --mssql_password MSSQL_PASSWORD --mssql_driver MSSQL_DRIVER
# without MSSQL tests
tox
```
or [pytest](https://pypi.org/project/pytest/)
```
pip install pytest ahjo sqlalchemy
pytest --mssql_host MSSQL_HOST --mssql_port MSSQL_PORT --mssql_username MSSQL_USER --mssql_password MSSQL_PASSWORD --mssql_driver MSSQL_DRIVER
# without MSSQL tests
pytest
```
Notice that tests have dependencies to packages [ahjo](https://pypi.org/project/ahjo/) and [SQL Alchemy](https://pypi.org/project/SQLAlchemy/). To succesfully run SQL Server tests, you must have permissions to create a new database in instance.
## MSI installers
Palje can be packaged into an MSI installer which can be used to install it into a Windows environment and easily update it later. Installers are self-contained, meaning that the package contains everything that is needed for running Palje (e.g. required parts of Python installation and all the 3rd party libraries and their dependencies are included).
### Types of MSI installers
There two types of installers, `user` and `system`. The `user` installer is suitable for single-user installations e.g. for a user who wants to run palje on their own workstation. For shared use, e.g. Azure Virtual Desktop, the `system` installer may be the better option: once installed, the tools are available for all users on that machine.
**Notice:** using the `system` installer requires administrator priviledges.
### Local MSI builds
**Notice:** using an unsigned installer can end up with Windows Defender blocking Palje as malware. There is an ALM Partners developer signing key available to overcome this problem. Ask team TA3 for help if you need to sign development MSIs for testing purposes.
To set up an environment for MSI builds, create a new venv, activate it, and install build dependencies.
```
python venv <name-of-venv>
./<name-of-venv>/Scripts/activate
pip install .[msibuild]
```
To build a `user` installer, use commands:
```
$env:PALJE_MSI_TARGET_TYPE="user"
python ./msi_build.py bdist_msi
```
To build a `system` installer, use commands:
```
$env:PALJE_MSI_TARGET_TYPE="system"
python ./msi_build.py bdist_msi
```
**Notice:** if you make changes to the code, you __must re-install the palje__ package (`pip install .` or `pip install .[msibuild]`) into the build venv for the changes to be included in the next MSI build. Editable installs don't work here, so don't use them!
# License
Copyright 2021 ALM Partners Oy
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Raw data
{
"_id": null,
"home_page": null,
"name": "palje",
"maintainer": "ALM Partners Oy",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "palje",
"author": "ALM Partners Oy",
"author_email": null,
"download_url": null,
"platform": null,
"description": "Palje\r\n====================\r\n\r\n# Description\r\nPalje is a tool for creating hierarchical documentation of SQL Server databases to Confluence wiki.\r\n\r\n# Dependencies\r\n* [pyodbc](https://pypi.org/project/pyodbc/)\r\n* [requests](https://pypi.org/project/requests/)\r\n\r\n# Install Guide\r\n\r\n## PyPI\r\nInstall from [Python Package Index](https://pypi.org/) with the following command:\r\n\r\n```\r\npip install palje\r\n```\r\n\r\n## Clone and install\r\n1. Clone this repository\r\n2. Install with pip\r\n\r\n```\r\ncd .\\palje\r\npip install [-e] .\r\n```\r\n\r\n## Development environment\r\n\r\nInstall and set up dev and test tooling with commands:\r\n\r\n```\r\npip install -e .[dev, test]\r\npre-commit install\r\n```\r\n\r\nThis takes `black` code formatting in use via `pre-commit`.\r\n\r\n# Usage\r\n\r\nPalje can be used either from the command line (CLI) or from the graphical user interface (GUI).\r\n\r\nNotice that there are two versions of the command-line tool: legacy `palje` and newer `palje2`. See below for details.\r\n\r\n## Prerequisites\r\n\r\n- Read access to the MSSQL database you wish to document\r\n - Data is read from documented database, information schema and system views\r\n - You can use either SQL authentication or Windows authentication (if available)\r\n\r\n- Write access to Confluence space on which you wish to create the documentation pages\r\n\r\n- Atlassian API Token for your account\r\n - Palje uses your registered account email and API token to authenticate to Confluence Cloud\r\n - Go to https://id.atlassian.com/manage/api-tokens\r\n - Choose \"Create API token\"\r\n - Give it a name\r\n - Token password will be created automatically, save this password\r\n\r\n## Remarks on compatibility\r\n\r\n- Palje has been tested on multiple SQL Server versions, including [SQL Server images](https://hub.docker.com/_/microsoft-mssql-server)\r\n- Palje has been tested on cloud instances, such as Azure SQL Database\r\n - Palje supports Azure Active Directory authentication with argument --authentication \"AAD\"\r\n- Palje has been tested to work with Confluence Cloud\r\n - There is a possibility that Palje works with Confluence Server since the Server REST API is similar to Cloud REST API\r\n - Notice that the authentication works differently in Confluence Server\r\n\r\n## Graphical user-interface\r\n\r\nNotice that GUI may be lacking some of the more advanced features that are available via CLI.\r\n\r\n\r\n\r\nLaunch Palje GUI from a shell with command:\r\n\r\n```\r\npalje-gui\r\n```\r\n\r\nSee the CLI documentation below for information on various parameters - it all applies to GUI, too.\r\n\r\n\r\n## CLI and arguments (current palje2 version)\r\n\r\nIn comparison to `palje`, the new `palje2` CLI is more flexible and adds more features for managing Confluence documentation e.g. deletion of Confluence page hierarchies.\r\n\r\nSee online help for up-to-date documentation for available options and sub-commands.\r\n```\r\npalje2 --help\r\n```\r\n\r\nTo see specific documentation for a sub-command, use the -h/--help switch after the sub-command e.g.\r\n\r\n```\r\npalje2 document --help\r\npalje2 delete --help\r\n```\r\n\r\n### Parameters from ENV vars\r\n\r\nWith `palje2` many parameters (e.g. Confluence authentication params) can be set into ENV variables from where they are automatically read at runtime. This makes continous use more user-friendly: less repetative typing, shorter and clearer commands, sensitive data stays out of sight, ...\r\n\r\nNotice that using ENV vars is optional: alternatively you can type parameters on the command line and/or leave them off and let `palje2` interactively prompt for any required parameter values.\r\n\r\nSee the online-documentation for supported ENV vars and their exact names.\r\n\r\nExample of setting ENV vars in PowerShell:\r\n\r\n```\r\n$env:PALJE_ATLASSIAN_USER_ID = \"firstname.lastname@organization.org\"\r\n$env:PALJE_ATLASSIAN_API_TOKEN = \"S3CR3T\"\r\n$env:PALJE_DB_SERVER = \"localhost,14330\"\r\n...\r\n```\r\n\r\nIf you want to unset an ENV var, you can do it like:\r\n\r\n```\r\n$env:PALJE_DB_PASSWORD = $null\r\n```\r\n\r\n## CLI and arguments (legacy version)\r\n\r\nSee online help for up-to-date documentation for available options.\r\n```\r\npalje -h\r\n```\r\n\r\n### Basic syntax\r\n\r\n```\r\npalje confluence-url space server database\r\n --parent-page PARENT_PAGE\r\n --schemas SCHEMAS [SCHEMAS ...]\r\n --dependent DEPENDENT [DEPENDENT ...]\r\n --db-driver DB_DRIVER\r\n --authentication AUTHENTICATION\r\n```\r\n\r\n| Argument | Required | Description | Type | Default Value |\r\n| --- | --- | --- | --- | --- |\r\n| confluence-url | Yes | The organisation's atlassian root page, https://<your-org>.atlassian.net/ | str | |\r\n| space | Yes | Space key of the Confluence space, in which the documentation is created | str | |\r\n| server | Yes | Host name of the SQL Server. Include port with comma | str | |\r\n| database | Yes | Name of the database that is documented | str | |\r\n| parent-page | No | Name or title of the Confluence page, under which the documentation is created | str | If page is not given, the documentation will be created to top level (under pages) |\r\n| schemas | No | Names of the schemas that are documented | list of str | If schemas not given, all schemas will be documented |\r\n| dependent | No | Names of the databases, where object dependencies are sought | list of str | If databases not given, dependencies are sought only in documented database |\r\n| db-driver | No | Name of the database driver | str | \"ODBC Driver 17 for SQL Server\" |\r\n| authentication | No | Authentication method to use. Options are \"SQL\", \"Windows\", \"AAD\" and \"AzureIdentity\". | str | \"SQL\"\r\n\r\n\r\n## Usage example\r\n\r\n\r\n### Command-line interface\r\n```\r\n# Run via a configured script endpoint (\"palje.exe\")\r\npalje \"https://<your-org>.atlassian.net/\" TEST \"localhost,1433\" MY_DB --schemas dbo store --dependent MY_OTHER_DB --authentication \"SQL\"\r\n\r\n# Optionally you also run palje as a Python library module\r\npython -m palje \"https://<your-org>.atlassian.net/\" TEST \"localhost,1433\" MY_DB --schemas dbo store --dependent MY_OTHER_DB --authentication \"SQL\"\r\n\r\n```\r\n### Output\r\n```\r\nUser for localhost,1433.MY_DB. If you wish to use Windows Authentication, hit enter: sa\r\nPassword for user sa:\r\nConfluence user for https://<your-org>.atlassian.net/: example.user@youremail.com\r\nAtlassian API token for user example.user@youremail.com:\r\n--------------------------\r\nObject dependencies are queried from the following databases: MY_DB, MY_OTHER_DB\r\n--------------------------\r\nPage DATABASE: MY_DB created.\r\nPage MY_DB.dbo created.\r\nPage Tables MY_DB.dbo created.\r\nPage MY_DB.dbo.schema_version created.\r\nPage MY_DB.store created.\r\nPage Tables MY_DB.store created.\r\nPage MY_DB.store.Clients created.\r\nPage MY_DB.store.Products created.\r\nPage Procedures MY_DB.store created.\r\nPage MY_DB.store.spSELECT created.\r\n```\r\n### Result\r\n#### Page hierarchy in Confluence\r\n\r\n\r\n#### Page showing the database objects\r\n\r\n\r\n#### Page showing the table information\r\n\r\n\r\n### Re-run\r\nRe-running the command will result updating the existing pages\r\n```\r\nPage DATABASE: MY_DB updated.\r\nPage MY_DB.dbo updated.\r\nPage Tables MY_DB.dbo updated.\r\nPage MY_DB.dbo.schema_version updated.\r\nPage MY_DB.store updated.\r\nPage Tables MY_DB.store updated.\r\nPage MY_DB.store.Clients updated.\r\nPage MY_DB.store.Products updated.\r\nPage Procedures MY_DB.store updated.\r\nPage MY_DB.store.spSELECT updated.\r\n```\r\nIf new objects have been created to database before re-run, new pages will be created for these objects. For example, if new procedure `store.spNEW_SELECT` is created to database, a new page `MY_DB.store.spNEW_SELECT` is created under page `Procedures MY_DB.store`.\r\n\r\nNotice that if you delete objects from database, Palje won't delete the corresponding pages from Confluence. You must manually delete the pages from wiki.\r\n\r\n## Tests\r\n\r\nRun tests with [tox](https://pypi.org/project/tox/)\r\n```\r\npip install tox # OR install as an optional depencency with palje itself: pip install .[test]\r\n\r\ntox -- --mssql_host MSSQL_HOST --mssql_port MSSQL_PORT --mssql_username MSSQL_USER --mssql_password MSSQL_PASSWORD --mssql_driver MSSQL_DRIVER\r\n\r\n# without MSSQL tests\r\ntox\r\n```\r\nor [pytest](https://pypi.org/project/pytest/)\r\n```\r\npip install pytest ahjo sqlalchemy\r\n\r\npytest --mssql_host MSSQL_HOST --mssql_port MSSQL_PORT --mssql_username MSSQL_USER --mssql_password MSSQL_PASSWORD --mssql_driver MSSQL_DRIVER\r\n\r\n# without MSSQL tests\r\npytest\r\n```\r\n\r\nNotice that tests have dependencies to packages [ahjo](https://pypi.org/project/ahjo/) and [SQL Alchemy](https://pypi.org/project/SQLAlchemy/). To succesfully run SQL Server tests, you must have permissions to create a new database in instance.\r\n\r\n## MSI installers\r\n\r\nPalje can be packaged into an MSI installer which can be used to install it into a Windows environment and easily update it later. Installers are self-contained, meaning that the package contains everything that is needed for running Palje (e.g. required parts of Python installation and all the 3rd party libraries and their dependencies are included).\r\n\r\n### Types of MSI installers\r\n\r\nThere two types of installers, `user` and `system`. The `user` installer is suitable for single-user installations e.g. for a user who wants to run palje on their own workstation. For shared use, e.g. Azure Virtual Desktop, the `system` installer may be the better option: once installed, the tools are available for all users on that machine.\r\n\r\n**Notice:** using the `system` installer requires administrator priviledges.\r\n\r\n### Local MSI builds\r\n\r\n**Notice:** using an unsigned installer can end up with Windows Defender blocking Palje as malware. There is an ALM Partners developer signing key available to overcome this problem. Ask team TA3 for help if you need to sign development MSIs for testing purposes.\r\n\r\nTo set up an environment for MSI builds, create a new venv, activate it, and install build dependencies.\r\n\r\n```\r\npython venv <name-of-venv>\r\n./<name-of-venv>/Scripts/activate\r\npip install .[msibuild]\r\n```\r\n\r\nTo build a `user` installer, use commands:\r\n\r\n```\r\n$env:PALJE_MSI_TARGET_TYPE=\"user\"\r\npython ./msi_build.py bdist_msi\r\n```\r\n\r\nTo build a `system` installer, use commands:\r\n\r\n```\r\n$env:PALJE_MSI_TARGET_TYPE=\"system\"\r\npython ./msi_build.py bdist_msi\r\n```\r\n\r\n**Notice:** if you make changes to the code, you __must re-install the palje__ package (`pip install .` or `pip install .[msibuild]`) into the build venv for the changes to be included in the next MSI build. Editable installs don't work here, so don't use them!\r\n\r\n# License\r\nCopyright 2021 ALM Partners Oy\r\n\r\nLicensed under the Apache License, Version 2.0 (the \"License\");\r\nyou may not use this file except in compliance with the License.\r\nYou may obtain a copy of the License at\r\n\r\n http://www.apache.org/licenses/LICENSE-2.0\r\n\r\nUnless required by applicable law or agreed to in writing, software\r\ndistributed under the License is distributed on an \"AS IS\" BASIS,\r\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r\nSee the License for the specific language governing permissions and\r\nlimitations under the License.\r\n",
"bugtrack_url": null,
"license": "Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. \"License\" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. \"Licensor\" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. \"Legal Entity\" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, \"control\" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. \"You\" (or \"Your\") shall mean an individual or Legal Entity exercising permissions granted by this License. \"Source\" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. \"Object\" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. \"Work\" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). \"Derivative Works\" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. \"Contribution\" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, \"submitted\" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as \"Not a Contribution.\" \"Contributor\" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a \"NOTICE\" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets \"[]\" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same \"printed page\" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.",
"summary": "A tool for creating hierarchical documentation of SQL Server databases to Confluence wiki.",
"version": "2.3.1",
"project_urls": {
"Repository": "https://github.com/ALMPartners/palje"
},
"split_keywords": [
"palje"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8380e5ff4d84bf740ae78897bae9e09bb2d95b6fdffc4a22e32ac0a8934eba87",
"md5": "6c468e3c71787cb6e9602595ed2124a9",
"sha256": "49530b382ff58eb5c682fbdcd7194c9e233226eb96ed8522b01b12521184e127"
},
"downloads": -1,
"filename": "palje-2.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c468e3c71787cb6e9602595ed2124a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 94028,
"upload_time": "2024-09-27T06:08:11",
"upload_time_iso_8601": "2024-09-27T06:08:11.609647Z",
"url": "https://files.pythonhosted.org/packages/83/80/e5ff4d84bf740ae78897bae9e09bb2d95b6fdffc4a22e32ac0a8934eba87/palje-2.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-27 06:08:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ALMPartners",
"github_project": "palje",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "palje"
}
