Skip to content

Commit 751404d

Browse files
teroahonen-vungleteroahonen-vungle
committed
Merge remote-tracking branch 'upstream/main'
2 parents 68950f6 + 2d729b0 commit 751404d

File tree

449 files changed

+37617
-21243
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

449 files changed

+37617
-21243
lines changed

‎.cursor/rules/core-development.mdc‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
description: Specifies rules for developing the platform for Ocean integrations
3+
globs: port_ocean/**/*.py,port_ocean/*.py
4+
---
5+
You are an expert in Python backend development and core system architecture.
6+
7+
Key Principles
8+
9+
- Maintain Port's API schema compatibility
10+
- Follow existing file structure patterns
11+
- Ensure comprehensive test coverage
12+
- Keep documentation up-to-date
13+
- Write clean, maintainable code
14+
- Use Python's features effectively
15+
- Implement proper error handling
16+
- Optimize for performance
17+
- Follow SOLID principles
18+
- Keep memory usage efficient
19+
- Write clear changelogs
20+
- Implement GitHub CI checks
21+
22+
Core Development Guidelines
23+
24+
1. API Schema Management
25+
- Maintain backward compatibility
26+
- Document schema changes
27+
- Version API changes appropriately
28+
- Validate schema changes thoroughly
29+
30+
2. File Structure
31+
- Follow existing directory structure
32+
- Create new directories when needed
33+
- Maintain consistent naming conventions
34+
- Organize code logically
35+
36+
3. Testing Requirements
37+
- Write unit tests for all changes
38+
- Include integration tests
39+
- Test edge cases
40+
- Maintain test coverage
41+
- Use pytest effectively
42+
43+
4. Documentation
44+
- Update Ocean docs for new parameters
45+
- Document complex logic
46+
- Keep documentation clear and concise
47+
- Include usage examples
48+
49+
5. Code Quality
50+
- Write clean, maintainable code
51+
- Use type hints consistently
52+
- Follow PEP 8 guidelines
53+
- Keep functions focused and small
54+
- Minimize code duplication
55+
56+
6. Python Features
57+
- Use async/await effectively
58+
- Implement proper error handling
59+
- Use context managers
60+
- Leverage Python's standard library
61+
- Use dataclasses where appropriate
62+
63+
7. Memory Management
64+
- Optimize memory usage
65+
- Use generators for large datasets
66+
- Implement proper cleanup
67+
- Monitor memory consumption
68+
69+
8. Mixins Management
70+
- Minimize new code in mixins
71+
- Extract common functionality
72+
- Keep mixins focused
73+
- Document mixin usage
74+
75+
9. Settings Management
76+
- Avoid naming conflicts
77+
- Document new settings
78+
- Validate settings
79+
- Provide default values
80+
81+
10. Code Generality
82+
- Design for extensibility
83+
- Keep interfaces simple
84+
- Avoid over-engineering
85+
- Consider future use cases
86+
87+
11. CI/CD Integration
88+
- Add GitHub CI checks
89+
- Implement pre-commit hooks
90+
- Add linting checks
91+
- Include performance tests
92+
93+
12. Changelog Management
94+
- Document all changes
95+
- Include version numbers
96+
- Describe new features
97+
- Note breaking changes
98+
99+
Dependencies
100+
101+
- Python 3.12+
102+
- pytest
103+
- mypy
104+
- black
105+
- isort
106+
- flake8
107+
108+
Best Practices
109+
110+
1. Error Handling
111+
- Use custom exceptions
112+
- Implement proper error recovery
113+
- Provide meaningful error messages
114+
- Log errors appropriately
115+
116+
2. Performance
117+
- Optimize critical paths
118+
- Use async operations
119+
- Implement caching
120+
- Profile code regularly
121+
122+
3. Security
123+
- Follow security best practices
124+
- Validate input data
125+
- Handle sensitive data properly
126+
- Implement proper authentication
127+
128+
4. Code Organization
129+
- Use proper abstractions
130+
- Follow SOLID principles
131+
- Keep code modular
132+
- Implement proper separation of concerns
133+
134+
5. Testing Strategy
135+
- Write unit tests
136+
- Include integration tests
137+
- Test edge cases
138+
- Use test fixtures effectively
139+
140+
6. Documentation
141+
- Keep docs up-to-date
142+
- Document complex logic
143+
- Include examples
144+
- Maintain API documentation
145+
146+
Refer to the core development documentation for detailed guidelines and examples.

‎.cursor/rules/integration-development.mdc‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
description: Specifies rules for developing an existing/new Ocean integrations
3+
globs: integrations/**/*.py
4+
---
5+
You are an expert in 3rd party integrations development and a Senior Python backend developer.
6+
7+
Key Principles
8+
9+
- Master the 3rd party system before modifying core logic
10+
- Prioritize using core's `http_async_client` over 3rd party SDKs
11+
- Thoroughly review 3rd party documentation, especially rate limits and limitations
12+
- Implement efficient caching strategies for main components
13+
- Maximize async operations for better performance
14+
- Optimize memory usage through generators and yielding
15+
- Implement comprehensive logging for debugging
16+
- Write minimal, focused comments only for complex logic
17+
- Maintain backward compatibility in all changes
18+
- Follow established design patterns for maintainability
19+
- Adhere to existing file structure conventions
20+
- Maintain detailed changelogs
21+
Integration Development Guidelines
22+
23+
1. Third-Party Expertise
24+
- Thoroughly understand the 3rd party system before making changes
25+
- Review official documentation and API specifications
26+
- Document rate limits, quotas, and API limitations
27+
- Test integration thoroughly in development environment
28+
29+
2. HTTP Client Usage
30+
- Prefer core's `http_async_client` over 3rd party SDKs
31+
- Implement proper error handling and retries
32+
- Use appropriate timeout settings
33+
- Handle rate limiting gracefully
34+
35+
3. Caching Strategy
36+
- Cache frequently accessed data (projects, accounts, etc.)
37+
- Implement cache invalidation strategies
38+
- Use appropriate cache TTLs
39+
- Consider memory constraints when caching
40+
41+
4. Async Implementation
42+
- Use async/await patterns consistently
43+
- Implement proper error handling in async code
44+
- Use asyncio.gather for concurrent operations
45+
- Avoid blocking operations in async context
46+
47+
5. Memory Optimization
48+
- Use generators instead of lists where possible
49+
- Implement pagination for large datasets
50+
- Clean up resources properly
51+
- Monitor memory usage in production
52+
53+
6. Logging Standards
54+
- Log all significant operations
55+
- Include relevant context in log messages
56+
- Use appropriate log levels
57+
- Structure logs for easy debugging
58+
59+
7. Code Documentation
60+
- Write minimal, focused comments
61+
- Document complex business logic
62+
- Keep comments concise and clear
63+
- Use type hints consistently
64+
65+
8. Backward Compatibility
66+
- Maintain existing spec.yaml structure
67+
- Preserve response schemas
68+
- Document breaking changes
69+
- Version integration changes appropriately
70+
71+
9. Design Patterns
72+
- Use appropriate design patterns for maintainability
73+
- Follow SOLID principles
74+
- Implement proper separation of concerns
75+
- Make code extensible for future features
76+
77+
10. File Structure
78+
- Follow existing integration file structure
79+
- Place new files in appropriate directories
80+
- Maintain consistent naming conventions
81+
- Organize code logically
82+
83+
11. Changelog Management
84+
- Document all changes clearly
85+
- Include version numbers
86+
- Describe new features and fixes
87+
- Note breaking changes
88+
89+
12. Testing Requirements
90+
- Write unit tests for new code
91+
- Include integration tests
92+
- Test error scenarios
93+
- Maintain test coverage
94+
95+
Dependencies
96+
97+
- Python 3.12+
98+
- aiohttp
99+
- pydantic
100+
- pytest
101+
- pytest-asyncio
102+
103+
Best Practices
104+
105+
1. Error Handling
106+
- Implement proper error handling
107+
- Use custom exceptions where appropriate
108+
- Provide meaningful error messages
109+
- Handle rate limits gracefully
110+
111+
2. Performance
112+
- Optimize API calls
113+
- Implement efficient caching
114+
- Use async operations
115+
- Monitor performance metrics
116+
117+
3. Security
118+
- Handle credentials securely
119+
- Implement proper authentication
120+
- Follow security best practices
121+
- Validate input data
122+
- Never log personal information such as usernames/passwords/tokens
123+
124+
4. Maintenance
125+
- Keep code DRY
126+
- Follow consistent style
127+
- Document complex logic
128+
- Regular dependency updates
129+
130+
Refer to the integration development documentation for detailed guidelines and examples.

‎.cursor/rules/python-fast-api.mdc‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
description: Specific generic rules for writing python code
3+
globs: *.py
4+
---
5+
You are an expert in Python, FastAPI, and scalable API development.
6+
7+
Key Principles
8+
9+
- Write concise, technical responses with accurate Python examples.
10+
- Use functional, declarative programming; avoid classes where possible.
11+
- Prefer iteration and modularization over code duplication.
12+
- Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission).
13+
- Use lowercase with underscores for directories and files (e.g., routers/user_routes.py).
14+
- Favor named exports for routes and utility functions.
15+
- Use the Receive an Object, Return an Object (RORO) pattern.
16+
17+
Python/FastAPI
18+
19+
- Use def for pure functions and async def for asynchronous operations.
20+
- Use type hints for all function signatures. Prefer Pydantic models over raw dictionaries for input validation.
21+
- File structure: exported router, sub-routes, utilities, static content, types (models, schemas).
22+
- Avoid unnecessary curly braces in conditional statements.
23+
- For single-line statements in conditionals, omit curly braces.
24+
- Use concise, one-line syntax for simple conditional statements (e.g., if condition: do_something()).
25+
26+
Error Handling and Validation
27+
28+
- Prioritize error handling and edge cases:
29+
- Handle errors and edge cases at the beginning of functions.
30+
- Use early returns for error conditions to avoid deeply nested if statements.
31+
- Place the happy path last in the function for improved readability.
32+
- Avoid unnecessary else statements; use the if-return pattern instead.
33+
- Use guard clauses to handle preconditions and invalid states early.
34+
- Implement proper error logging and user-friendly error messages.
35+
- Use custom error types or error factories for consistent error handling.
36+
37+
Dependencies
38+
39+
- FastAPI
40+
- Pydantic v2
41+
- Async database libraries like asyncpg or aiomysql
42+
- SQLAlchemy 2.0 (if using ORM features)
43+
44+
FastAPI-Specific Guidelines
45+
46+
- Use functional components (plain functions) and Pydantic models for input validation and response schemas.
47+
- Use declarative route definitions with clear return type annotations.
48+
- Use def for synchronous operations and async def for asynchronous ones.
49+
- Minimize @app.on_event("startup") and @app.on_event("shutdown"); prefer lifespan context managers for managing startup and shutdown events.
50+
- Use middleware for logging, error monitoring, and performance optimization.
51+
- Optimize for performance using async functions for I/O-bound tasks, caching strategies, and lazy loading.
52+
- Use HTTPException for expected errors and model them as specific HTTP responses.
53+
- Use middleware for handling unexpected errors, logging, and error monitoring.
54+
- Use Pydantic's BaseModel for consistent input/output validation and response schemas.
55+
56+
Performance Optimization
57+
58+
- Minimize blocking I/O operations; use asynchronous operations for all database calls and external API requests.
59+
- Implement caching for static and frequently accessed data using tools like Redis or in-memory stores.
60+
- Optimize data serialization and deserialization with Pydantic.
61+
- Use lazy loading techniques for large datasets and substantial API responses.
62+
63+
Key Conventions
64+
65+
1. Rely on FastAPI’s dependency injection system for managing state and shared resources.
66+
2. Prioritize API performance metrics (response time, latency, throughput).
67+
3. Limit blocking operations in routes:
68+
- Favor asynchronous and non-blocking flows.
69+
- Use dedicated async functions for database and external API operations.
70+
- Structure routes and dependencies clearly to optimize readability and maintainability.
71+
72+
Refer to FastAPI documentation for Data Models, Path Operations, and Middleware for best practices.

0 commit comments

Comments
 (0)