- « Explore Project docs »
Report bug
@@ -21,7 +20,7 @@
# Getting Started
-This repository contains a cookiecutter template for generating a Bot using
+This repository contains a cookiecutter template for generating a Bot using
BotCity's Python Framework.
To create a templated project all you need to do is:
@@ -43,8 +42,3 @@ mkdocs build
This will generate the HTML documentation in the `<>/site`
folder. Look for the `index.html` file and open it with your browser.
-
-# Online Documentation
-
-More information about cookiecutter and how to organize your Bot project can be found
-at https://botcity-dev.github.io/bot-python-template/.
diff --git a/cookiecutter.json b/cookiecutter.json
index c37df86..d2da37f 100644
--- a/cookiecutter.json
+++ b/cookiecutter.json
@@ -1,6 +1,4 @@
{
"project_type": ["Desktop", "Web", "Both", "Custom"],
- "bot_id": "botPython",
- "project_name": "Python Bot",
- "project_short_description": "Python package for a BotCity bot."
+ "bot_id": "botPython"
}
diff --git a/docs-requirements.txt b/docs-requirements.txt
deleted file mode 100644
index 4794cd4..0000000
--- a/docs-requirements.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-mkdocs
-mkdocstrings
-mkdocs-material
-livereload
-pygments
\ No newline at end of file
diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico
deleted file mode 100644
index 1645eec..0000000
Binary files a/docs/assets/favicon.ico and /dev/null differ
diff --git a/docs/assets/logo.png b/docs/assets/logo.png
deleted file mode 100644
index 516117d..0000000
Binary files a/docs/assets/logo.png and /dev/null differ
diff --git a/docs/building.md b/docs/building.md
deleted file mode 100644
index 9c05379..0000000
--- a/docs/building.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Building the Package
-
-Since the bot is a python package, it is recommended to generate a source distribution.
-
-For that we provide build scripts (`build.bat` and `build.bat`) which just do the following:
-
-```shell
-python setup.py sdist
-```
-
-This process will generate a `dist` folder with the compressed project source code.
-
-
-# Installing
-
-After that is done you can install the package generated with:
-
-```shell
-pip install dist/botPython-1.0.tar.gz # or .zip if running on Windows
-```
-
-Or simply using the following command:
-
-```shell
-pip install -e .
-```
-
-!!! tip
- If you are using the BotCity Maestro server, the BotRunner will take care of installing
- your package into a virtual environment for execution in your automation machine.
- All you need to do is use the BotCLI command line interface to deploy and release your
- package.
-
- ```shell
- # For deploy:
- java -jar botCLI.jar bot deploy -botId "botPython" -version 1.0 -file "./dist/botPython-1.0.tar.gz" -python
-
- # For update of an existing version file:
- java -jar botCLI.jar bot update -botId "botPython" -version 1.0 -file "./dist/botPython-1.0.tar.gz" -python
-
- # For release:
- java -jar botCLI.jar bot release -botId "botPython" -version 1.0
- ```
diff --git a/docs/creating.md b/docs/creating.md
deleted file mode 100644
index 0bf1558..0000000
--- a/docs/creating.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Creating a new Project using Cookiecutter
-
-```bash
-python -m cookiecutter https://github.com/botcity-dev/bot-python-template/archive/main.zip
-```
-
-When running this command you will be prompted for the following information:
-
-!!! warning inline end
- **bot_id** value **must** match the Bot label configured on BotMaestro if using the integration.
-
-- **project_type**: This will define which bot template is generated.
- The options are **Desktop**, **Web**, **Both** or **Custom**.
- - Select **Desktop** for general Desktop or non-headless Web automations.
- - Select **Web** if your automation involve only websites.
- - Select **Both** if your automation involves a mix.
- - Select **Custom** if you would like to add your own libraries or create an automation using only BotCity plugins.
-
-- **bot_id**: This will be the name of your Python module. It can only contain letters (a-z or A-Z), underscore (_) and must end with a letter (a-z or A-Z).
-
-- **project_name**: This is the name of the project. You can pick any name you would like.
-
-- **project_short_description**: This is a short description of the bot.
-
-Over the next chapter we will explore the package and guide you on the most common operations to be executed.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index bd666e5..0000000
--- a/docs/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Dependencies
-
-This project assumes that you have [Python](https://www.python.org/) and [pip](https://pip.pypa.io/en/stable/) installed.
-
-## Cookiecutter
-
-Here is how to install cookiecutter:
-```bash
-python -m pip install --upgrade cookiecutter
-```
diff --git a/docs/next.md b/docs/next.md
deleted file mode 100644
index ce0e395..0000000
--- a/docs/next.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Next Steps
-
-Congratulations! By now you should have created your first bot and executed it a couple of times.
-
-If you do have questions or suggestions feel free to reach out via one of the following channels:
-
-- [BotCity Community](http://community.botcity.dev/)
-- [BotCity Core Framework - Python](https://github.com/botcity-dev/botcity-framework-core-python)
-- [BotCity Web Framework - Python](https://github.com/botcity-dev/botcity-framework-web-python)
-- [BotCity Template Project - Python](https://github.com/botcity-dev/bot-python-template)
-
-Have fun automating!
\ No newline at end of file
diff --git a/docs/project.md b/docs/project.md
deleted file mode 100644
index 0fd6880..0000000
--- a/docs/project.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# Exploring the project
-
-If you execute the cookiecutter command above and select the default values, you will end up
-with the following structure:
-```
- botPython
- ├── MANIFEST.in <- This file defines the content of the package such as images.
- ├── README.md <- Simple README file for your bot project.
- ├── VERSION <- This file defines the Bot package version.
- ├── botPython <- Main module for your Bot package.
- │ ├── __init__.py
- │ ├── __main__.py <- Entrypoint for the module. You don't need to bother with this file.
- │ ├── bot.py <- Module for your bot code. Here is where you will develop your bot.
- │ └── resources <- Folder containing resources useful for the Bot.
- ├── build.bat <- Batch script to generate the package
- ├── build.sh <- Shell script to generate the package
- ├── requirements.txt <- File describing the python dependencies for your Bot.
- └── setup.py <- Setup file for the package.
-```
-
-The main files to be modified are:
-
-- **bot.py**: Change this file and add here the code for your bot.
-
-- **resources**: Add into this folder files to be used with your bot such as images, spreadsheets and etc.
-
-- **VERSION**: Change the content of this file when updating the version of your bot.
-It is recommended to use versions in the format X.Y. E.g. 1.0, 1.1, 2.5, 3.10.
-
-## Resources
-
-By default this project is configured to add into the package all files and subfolders that
-are added under the `resources` folder.
-
-The bot base class offers an utility method to handle files taking into consideration the package path.
-Please refer to the BotCity Framework documentation under the Bot API for the `get_resource_abspath` method.
-
-Here is an example:
-
-```python
-class Bot(DesktopBot):
- def action(self, execution):
- # Add the resource start.png.
- # Note the self.get_resource_abspath call to handle
- # the package path
- self.add_image("start", self.get_resource_abspath("start.png"))
-```
-
-!!! warning
- If adding **new** resource folders parallel to the existing `resources` folder,
- make sure to change the `MANIFEST.in` file and also add the folder name
- under `package_data` at `setup.py`.
-
-## Additional Dependencies
-
-If you need to add additional Python packages for use with your bot project, make sure to add them into the `requirements.txt`.
-
-This is required for the BotRunner to be able to install and run your bot.
-
-## Bot Code
-
-This template project contains a skeleton class under `bot.py` with an initial example
-which opens up the browser with the BotCity website.
-
-Depending on your selection of the Project Type, the template will either use as base class the `DesktopBot` or `WebBot`.
-In both cases, the base class contains all the functions of the BotCity Python Core Framework
-as methods so please keep in mind to use `self.` when invoking the methods.
-
-### Example of a Desktop Bot skeleton:
-```python
-class Bot(DesktopBot):
- def action(self, execution):
- # using browse from browser module
- self.browse(...)
- # using find from display module
- self.find(...)
- # using mouse_move from mouse module
- self.mouse_move(x=100, y=200)
- # using enter from keyboard module
- self.enter()
-```
-
-### Example of a Web Bot skeleton:
-```python
-class Bot(WebBot):
- def action(self, execution):
- # Configure whether or not to run on headless mode
- self.headless = False
-
- # using browse from browser module
- self.browse(...)
- # using find from display module
- self.find(...)
- # using mouse_move from mouse module
- self.mouse_move(x=100, y=200)
- # using enter from keyboard module
- self.enter()
-
- # Stop the browser and clean up
- self.stop_browser()
-
-```
-
-
-!!! warning
- In case you use a different module for your main bot (instead of the default `bot.py`),
- make sure to change the `__main__.py` file to load the proper module.
diff --git a/docs/running.md b/docs/running.md
deleted file mode 100644
index b819d71..0000000
--- a/docs/running.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# Running Your Code
-
-This chapter will cover a couple different ways in which you can run your code for testing
-and production.
-
-## Installing dependencies
-
-Before running for the first time we need to install the dependencies required by the project.
-From the project main folder, execute the following command on the command line:
-```bash
-python -m pip install -e .
-```
-
-This will install your package on development mode and also take care of installing the dependencies.
-After that you are ready to proceed and run your code.
-
-## Direct execution via IDE or Command Line
-
-The `bot.py` file inside of the package has special code which invokes the `main` method
-on the bot class. This allow for direct execution of the bot via your favorite IDE or the
-command line.
-```python
-if __name__ == '__main__':
- Bot.main()
-```
-
-Here is how to start the code via the command line.
-```shell
-python bot.py
-```
-
-## Using the Module Entry Point
-
-The package has a module entry point `__main__.py` which imports the `bot.py` module and
-dynamically identify the Bot class for execution.
-
-To start your bot via the entry point do:
-
-```shell
-# Assuming your bot_id used during creation of the package
-# is botPython. Adjust as needed for your case.
-python -m botPython
-```
-
-!!! note
- This is the method used by the BotCity BotRunner when using the Bot Maestro orchestration.
diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py
index 11e374b..4e9156c 100644
--- a/hooks/post_gen_project.py
+++ b/hooks/post_gen_project.py
@@ -1,6 +1,7 @@
import os
project_type = "{{cookiecutter.project_type | lower}}"
+bot_id = "{{ cookiecutter.bot_id|replace(' ', '_') }}"
proj_files = {
"desktop": {"remove": ["webbot.py", "bothbot.py", "custombot.py"], "use": None},
@@ -15,7 +16,7 @@
raise ValueError(f"Invalid project type: {project_type}")
for f in config["remove"]:
- os.remove(os.path.join("{{cookiecutter.bot_id}}", f))
+ os.remove(f)
if config["use"]:
- os.rename(os.path.join("{{cookiecutter.bot_id}}", config["use"]), os.path.join("{{cookiecutter.bot_id}}", "bot.py"))
+ os.rename(config["use"], "bot.py")
diff --git a/hooks/pre_gen_project.py b/hooks/pre_gen_project.py
deleted file mode 100644
index 06e0a64..0000000
--- a/hooks/pre_gen_project.py
+++ /dev/null
@@ -1,12 +0,0 @@
-import re
-import sys
-
-bot_id = '{{ cookiecutter.bot_id }}'
-
-pattern = re.compile("^[a-z|A-Z]+[a-z|A-Z|_]*[a-z|A-Z]$")
-
-if not pattern.match(bot_id):
- print('ERROR: bot_id can only contain letters [a-z or A-Z], underscore (_) and must end with a letter [a-z or A-Z].')
-
- # exits with status 1 to indicate failure
- sys.exit(1)
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
deleted file mode 100644
index b8a5d1f..0000000
--- a/mkdocs.yml
+++ /dev/null
@@ -1,71 +0,0 @@
-site_name: Template Bot Project - Python
-repo_url: https://github.com/botcity-dev/bot-python-template
-repo_name: ""
-copyright: BotCity © - All rights reserved
-
-nav:
- - Home: index.md
- - Creating a Bot: creating.md
- - Exploring the Project: project.md
- - Building the Package: building.md
- - Running your Code: running.md
- - Next Steps: next.md
-
-theme:
- icon:
- repo: fontawesome/brands/github
- name: material
- favicon: assets/favicon.ico
- logo: assets/logo.png
- features:
- - navigation.top
- palette:
- - media: "(prefers-color-scheme: light)"
- scheme: default
- primary: white
- toggle:
- icon: material/toggle-switch-off-outline
- name: Switch to dark mode
- - media: "(prefers-color-scheme: dark)"
- scheme: slate
- primary: black
- toggle:
- icon: material/toggle-switch
- name: Switch to light mode
-
-extra:
- generator: false
- social:
- - icon: fontawesome/brands/github
- link: https://github.com/botcity-dev/bot-python-template
- name: BotCity Maestro SDK - Python -> GitHub
- - icon: fontawesome/brands/twitter
- link: https://twitter.com/botcitydev
- name: BotCity on Twitter
- analytics:
- provider: google
- property: UA-203228041-1
-
-markdown_extensions:
- - attr_list
- - admonition
- - pymdownx.highlight
- - pymdownx.superfences
-
-plugins:
- - search
- - mkdocstrings:
- default_handler: python
- watch:
- - botcity/maestro
- handlers:
- python:
- selection:
- inherited_members: false
- filters:
- - "!^_" # exclude all members starting with _
- - "^__init__$" # but always include __init__ modules and methods
- - "!([a-z])*([A-Z])" # exclude camelCase elements
- rendering:
- show_source: false
- show_root_heading: true
diff --git a/{{ cookiecutter.bot_id.replace(' ', '_') }}/MANIFEST.in b/{{ cookiecutter.bot_id.replace(' ', '_') }}/MANIFEST.in
deleted file mode 100644
index 20b602a..0000000
--- a/{{ cookiecutter.bot_id.replace(' ', '_') }}/MANIFEST.in
+++ /dev/null
@@ -1,11 +0,0 @@
-include README.rst
-include VERSION
-include requirements.txt
-
-recursive-exclude * __pycache__
-recursive-exclude * *.py[co]
-
-recursive-include {{ cookiecutter.bot_id|replace(' ', '_') }}/resources *
-
-# If including data files in the package, add them like:
-# include path/to/data_file
diff --git a/{{ cookiecutter.bot_id.replace(' ', '_') }}/README.md b/{{ cookiecutter.bot_id.replace(' ', '_') }}/README.md
deleted file mode 100644
index b2e1afb..0000000
--- a/{{ cookiecutter.bot_id.replace(' ', '_') }}/README.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# {{ cookiecutter.project_name }}
-
-{{ cookiecutter.project_short_description}}
-
diff --git a/{{ cookiecutter.bot_id.replace(' ', '_') }}/VERSION b/{{ cookiecutter.bot_id.replace(' ', '_') }}/VERSION
deleted file mode 100644
index 9f8e9b6..0000000
--- a/{{ cookiecutter.bot_id.replace(' ', '_') }}/VERSION
+++ /dev/null
@@ -1 +0,0 @@
-1.0
\ No newline at end of file
diff --git a/{{ cookiecutter.bot_id.replace(' ', '_') }}/bot.py b/{{ cookiecutter.bot_id.replace(' ', '_') }}/bot.py
new file mode 100644
index 0000000..003e575
--- /dev/null
+++ b/{{ cookiecutter.bot_id.replace(' ', '_') }}/bot.py
@@ -0,0 +1,60 @@
+"""
+WARNING:
+
+Please make sure you install the bot with `pip install -e .` in order to get all the dependencies
+on your Python environment.
+
+Also, if you are using PyCharm or another IDE, make sure that you use the SAME Python interpreter
+as your IDE.
+
+If you get an error like:
+```
+ModuleNotFoundError: No module named 'botcity'
+```
+
+This means that you are likely using a different Python interpreter than the one used to install the bot.
+To fix this, you can either:
+- Use the same interpreter as your IDE and install your bot with `pip install -e .`
+- Use the same interpreter as the one used to install the bot (`pip install -e .`)
+
+Please refer to the documentation for more information at https://documentation.botcity.dev/
+"""
+
+# Import for the Desktop Bot
+from botcity.core import DesktopBot
+
+# Import for integration with BotCity Maestro SDK
+from botcity.maestro import *
+
+# Disable errors if we are not connected to Maestro
+BotMaestroSDK.RAISE_NOT_CONNECTED = False
+
+def main():
+ # Runner passes the server url, the id of the task being executed,
+ # the access token and the parameters that this task receives (when applicable).
+ maestro = BotMaestroSDK.from_sys_args()
+ ## Fetch the BotExecution with details from the task, including parameters
+ execution = maestro.get_execution()
+
+ print(f"Task ID is: {execution.task_id}")
+ print(f"Task Parameters are: {execution.parameters}")
+
+ bot = DesktopBot()
+ bot.browse("http://www.botcity.dev")
+
+ # Implement here your logic...
+ ...
+
+ # Uncomment to mark this task as finished on BotMaestro
+ # maestro.finish_task(
+ # task_id=execution.task_id,
+ # status=AutomationTaskFinishStatus.SUCCESS,
+ # message="Task Finished OK."
+ # )
+
+def not_found(label):
+ print(f"Element not found: {label}")
+
+
+if __name__ == '__main__':
+ main()
\ No newline at end of file
diff --git a/{{ cookiecutter.bot_id.replace(' ', '_') }}/bothbot.py b/{{ cookiecutter.bot_id.replace(' ', '_') }}/bothbot.py
new file mode 100644
index 0000000..d862e72
--- /dev/null
+++ b/{{ cookiecutter.bot_id.replace(' ', '_') }}/bothbot.py
@@ -0,0 +1,90 @@
+"""
+WARNING:
+
+Please make sure you install the bot with `pip install -e .` in order to get all the dependencies
+on your Python environment.
+
+Also, if you are using PyCharm or another IDE, make sure that you use the SAME Python interpreter
+as your IDE.
+
+If you get an error like:
+```
+ModuleNotFoundError: No module named 'botcity'
+```
+
+This means that you are likely using a different Python interpreter than the one used to install the bot.
+To fix this, you can either:
+- Use the same interpreter as your IDE and install your bot with `pip install -e .`
+- Use the same interpreter as the one used to install the bot (`pip install -e .`)
+
+Please refer to the documentation for more information at https://documentation.botcity.dev/
+"""
+
+
+# Import for the Desktop Bot
+from botcity.core import DesktopBot
+
+# Import for the Web Bot
+from botcity.web import WebBot, Browser, By
+
+# Import for integration with BotCity Maestro SDK
+from botcity.maestro import *
+
+# Disable errors if we are not connected to Maestro
+BotMaestroSDK.RAISE_NOT_CONNECTED = False
+
+def main():
+ # Runner passes the server url, the id of the task being executed,
+ # the access token and the parameters that this task receives (when applicable).
+ maestro = BotMaestroSDK.from_sys_args()
+ ## Fetch the BotExecution with details from the task, including parameters
+ execution = maestro.get_execution()
+
+ print(f"Task ID is: {execution.task_id}")
+ print(f"Task Parameters are: {execution.parameters}")
+
+ desktop_bot = DesktopBot()
+
+ # Execute operations with the DesktopBot as desired
+ # desktop_bot.control_a()
+ # desktop_bot.control_c()
+ # value = desktop_bot.get_clipboard()
+
+ webbot = WebBot()
+
+ # Configure whether or not to run on headless mode
+ webbot.headless = False
+
+ # Uncomment to change the default Browser to Firefox
+ # webbot.browser = Browser.FIREFOX
+
+ # Uncomment to set the WebDriver path
+ # webbot.driver_path = "