René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Review and standardize all example code before cuda.core 1.0.0 release","articleBody":"### Motivation\n\nOur example code is the first thing users reach for. The current examples were written at different times by different authors and have accumulated inconsistencies in structure, style, naming, and resource management. We need to review every example across both `cuda.core` and `cuda.bindings` to ensure they present a polished, consistent experience for 1.0.0.\n\nEach sub-issue below is a self-contained work item — claim one by assigning yourself to it.\n\n### Known inconsistencies to evaluate\n\nThe following cross-cutting concerns have been identified. Each should be discussed by the team and resolved consistently across all examples.\n\n#### 1. File headers and copyright years\n- Copyright years are split: 7 files use `2024-2025`, 4 files use `2025` only.\n- The team should decide on one approach (e.g., always `2024-2025`, or year-of-creation to present).\n\n#### 2. Description block style\n- Some files use a single-line description: `\"This demo illustrates how to...\"`\n- Others use numbered bullet-point lists describing multiple concepts.\n- Some include usage instructions (`## Usage:` with pip/python commands), others don't.\n\n#### 3. Import ordering\n- At least 5 different import ordering patterns exist across the 11 cuda.core examples alone.\n- Variations: some start with `sys`, some have no stdlib imports, some use try/except for optional deps inline.\n- No consistent grouping (stdlib → third-party → cuda).\n\n#### 4. `if __name__ == \"__main__\"` guard\n- Only 4 of 11 cuda.core examples use a `__main__` guard (`show_device_properties.py`, `jit_lto_fractal.py`, `strided_memory_view_gpu.py`, `strided_memory_view_cpu.py`).\n- The other 7 run all code at module level.\n\n#### 5. Resource cleanup\n- Most examples do NOT close streams or buffers explicitly.\n- Only `saxpy.py` and `memory_ops.py` demonstrate explicit `close()` calls.\n- `strided_memory_view_gpu.py` uses a `finally` block for cleanup, others don't.\n- No examples use context managers for resource management.\n\n#### 6. Naming conventions\n- Stream variables: `s` vs `stream` vs `stream0`/`stream1`.\n- Kernel variables: `ker` vs `add_kernel` vs `gpu_ker`.\n- Device variables: `dev` vs `dev0`/`dev1` vs inline `Device()`.\n- Config objects are mostly `config`, but multi-config uses `config0`/`config1`.\n\n#### 7. Error handling and early-exit patterns\n- Some files use `sys.exit(0)` for unsupported configurations; others silently skip.\n- NumPy version checking uses two different APIs (`np.__version__ \u003c \"2.1.0\"` vs `np.lib.NumpyVersion()`).\n- Validation is a mix of `assert` statements and `print` + `sys.exit`.\n\n#### 8. Output and success messages\n- Completion messages vary: `\"done!\"`, `\"done\"` (no exclamation), `\"Example completed successfully!\"`, `\"All tests passed successfully!\"`, `\"Memory management example completed!\"`, or no message at all.\n- Some examples print intermediate progress, others are silent until the end.\n- Some use `sys.stderr` for warnings/info, others use `stdout`.\n\n#### 9. External dependencies\n- CuPy is required by 7 of 11 cuda.core files — is this the right default, or should more examples be dependency-light?\n- Only `show_device_properties.py` has zero external dependencies.\n- Optional dependency handling (try/except) is inconsistent.\n\n#### 10. Documentation coverage\n- Neither `cuda_core/examples/` nor `cuda_bindings/examples/` has a README.\n- Some examples are referenced in docs (`getting-started.rst`), others are not.\n- Consider whether each example should be linked from the documentation.\n\n### Sub-issues\n\nEach sub-issue below is a self-contained work item that can be claimed and driven independently. Assign yourself to a sub-issue to own it. Each sub-issue should result in one or more PRs that update **all** affected example files across both packages.\n\n- [ ] #1674 — Standardize file structure conventions\n- [ ] #1675 — Standardize naming conventions\n- [ ] #1676 — Standardize resource cleanup\n- [ ] #1677 — Standardize imports and dependency policy\n- [ ] #1678 — Standardize error handling and output\n- [ ] #1679 — Standardize file headers and copyright years\n- [ ] #1680 — Audit example coverage in documentation\n\n### How to contribute\n\n1. **Claim a sub-issue**: Assign yourself to one of the sub-issues above.\n2. **Propose a convention**: Comment on your sub-issue with a proposed standard for team review.\n3. **Apply across all files**: Once the convention is agreed upon, update all affected examples in both `cuda_core/examples/` and `cuda_bindings/examples/`.\n4. **Submit a PR** referencing this issue and the sub-issue number.\n5. **Check off the file-level boxes** in the Scope section above as files are updated.","author":{"url":"https://github.com/rparolin","@type":"Person","name":"rparolin"},"datePublished":"2026-02-20T21:34:02Z","url":"https://github.com/NVIDIA/cuda-python/issues/1673"}