feat: implement a generic overlap detector and other library fixups (#19

)

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+.vscode/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -22,45 +22,57 @@ pip install bedspec
 ### Writing
 
 ```python
-from bedspec import Bed3
-from bedspec import BedWriter
-
-bed = Bed3("chr1", start=2, end=8)
+from bedspec import Bed3, BedWriter
 
 with BedWriter[Bed3].from_path("test.bed") as writer:
-    writer.write(bed)
+    writer.write(Bed3("chr1", start=2, end=8))
 ```
 
 ### Reading
 
 ```python
-from bedspec import Bed3
-from bedspec import BedReader
+from bedspec import Bed3, BedReader
 
 with BedReader[Bed3].from_path("test.bed") as reader:
-    for bed in reader:
-        print(bed)
+    print(list(reader))
 ```
 ```console
-Bed3(contig="chr1", start=2, start=8)
+[Bed3(contig="chr1", start=2, start=8)]
 ```
 
 ### BED Types
 
-This package provides pre-defined classes for the following BED formats:
+This package provides builtin classes for the following BED formats:
 
 ```python
 from bedspec import Bed2
 from bedspec import Bed3
 from bedspec import Bed4
 from bedspec import Bed5
 from bedspec import Bed6
+from bedspec import BedGraph
 from bedspec import BedPE
 ```
 
-### Custom BED Types
+### Overlap Detection
+
+Use a fast overlap detector for any collection of interval types, including third-party:
+
+```python
+from bedspec import Bed3, Bed4
+from bedspec.overlap import OverlapDetector
+
+bed1: Bed4 = Bed4(contig="chr1", start=1, end=4, name="bed1")
+bed2: Bed4 = Bed4(contig="chr1", start=5, end=9, name="bed2")
+
+detector: OverlapDetector[Bed4] = OverlapDetector([bed1, bed2])
+
+assert detector.get_overlapping(Bed3(contig="chr1", start=2, 3)) == bed1
+```
+
+### Create Custom BED Types
 
-To create a custom BED record, inherit from the relevent BED-type:
+To create a custom BED record, inherit from the relevant BED-type:
 
 | Type        | Description                                          |
 | ---         | ---                                                  |
@@ -75,7 +87,7 @@ from dataclasses import dataclass
 
 from bedspec import SimpleBed
 
-@dataclass
+@dataclass(eq=True, frozen=True)
 class MyCustomBed(SimpleBed):
     contig: str
     start: int

bedspec/__init__.py

@@ -1,19 +1,19 @@
 # ruff: noqa: F401
-from ._bedspec import COMMENT_PREFIXES
-from ._bedspec import MISSING_FIELD
 from ._bedspec import Bed2
 from ._bedspec import Bed3
 from ._bedspec import Bed4
 from ._bedspec import Bed5
 from ._bedspec import Bed6
 from ._bedspec import BedColor
+from ._bedspec import BedGraph
 from ._bedspec import BedPE
-from ._bedspec import BedReader
 from ._bedspec import BedStrand
 from ._bedspec import BedType
-from ._bedspec import BedWriter
-from ._bedspec import Locatable
 from ._bedspec import PairBed
 from ._bedspec import PointBed
 from ._bedspec import SimpleBed
-from ._bedspec import Stranded
+from ._io import BedReader
+from ._io import BedWriter
+from ._types import GenomicSpan
+from ._types import Named
+from ._types import Stranded